Error handling | SurrealDB

Handle failures in version 2 of the PHP SDK with the typed exception hierarchy rooted at SurrealException.

Version 2 of the PHP SDK throws typed exceptions for different failures. They all extend SurrealException, which in turn extends PHP's RuntimeException. This lets you catch SDK errors broadly or target a specific failure with an instanceof check or a catch type.

Common exceptions

All exceptions live in the SurrealDB\SDK\Exceptions namespace.

Exception	Thrown when
`SurrealException`	Base class for every SDK error
`ConnectionUnavailableException`	An operation runs without an active connection
`HttpConnectionException`	An HTTP request fails with a non-success status
`AuthenticationException`	Sign in, sign up, or token renewal fails
`MissingNamespaceDatabaseException`	An operation needs a namespace or database that is not selected
`ServerException`	The server reports an error (base for query errors)
`QueryException`	A statement fails to execute
`UnsupportedVersionException`	The server version is outside the supported range
`UnsupportedFeatureException`	The engine does not support a requested feature
`UnavailableFeatureException`	The server version does not support a requested feature

Catching exceptions

Catch a specific type for fine-grained handling, or SurrealException to handle any SDK error.

use SurrealDB\SDK\Auth\RootAuth;
use SurrealDB\SDK\Exceptions\AuthenticationException;
use SurrealDB\SDK\Exceptions\ConnectionUnavailableException;
use SurrealDB\SDK\Exceptions\SurrealException;

try {
    $db->signin(new RootAuth('root', 'wrong'));
} catch (AuthenticationException $error) {
    echo 'Invalid credentials';
} catch (ConnectionUnavailableException $error) {
    echo 'Not connected to a database';
} catch (SurrealException $error) {
    echo 'SDK error: ' . $error->getMessage();
}

Connection and HTTP errors

A ConnectionUnavailableException is thrown when you run an operation without a connection. Over HTTP, a failed request throws HttpConnectionException, which exposes the status code, status text, and response body.

use SurrealDB\SDK\Exceptions\HttpConnectionException;

try {
    $db->run('SELECT * FROM person');
} catch (HttpConnectionException $error) {
    echo "HTTP {$error->status}: {$error->statusText}";
}

Query errors

When a statement fails, the SDK throws a ServerException (or a subclass such as QueryException). The exception carries the server's kind, message, and any details.

use SurrealDB\SDK\Exceptions\ServerException;

try {
    $db->run('SELECT * FROM');
} catch (ServerException $error) {
    echo "[{$error->kind}] {$error->getMessage()}";
}

Version mismatches

The SDK checks the server version on connect. If it is outside the supported range, it throws UnsupportedVersionException with the reported version and the supported bounds. Disable the check with the versionCheck option on connect().

use SurrealDB\SDK\Exceptions\UnsupportedVersionException;

try {
    $db->connect('ws://127.0.0.1:8000/rpc');
} catch (UnsupportedVersionException $error) {
    echo "Version {$error->version} is not supported " .
        "(requires >= {$error->minimum} < {$error->maximum})";
}

Listening to connection errors

Errors that happen outside a direct method call, such as a failed reconnection, are delivered through the error event rather than thrown. Subscribe with subscribe().

$db->subscribe('error', function (\Throwable $error): void {
    error_log('Connection error: ' . $error->getMessage());
});

Learn more

Surreal API reference for the methods that raise these errors
Connecting to SurrealDB for version and reconnection settings
Authentication for handling sign-in failures