# Error handling

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.

The error kinds, wire codes and structured shape behind these are documented once in [Errors](/docs/reference/rest-api/errors.md), which applies to every SDK and protocol.

## 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.

```php
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.

```php
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`.

```php
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()`](/docs/reference/php/v2/concepts/connecting-to-surrealdb.md#connection-options).

```php
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()`.

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

## Learn more

- [Surreal API reference](/docs/reference/php/v2/api/core.md) for the methods that raise these errors
- [Connecting to SurrealDB](/docs/reference/php/v2/concepts/connecting-to-surrealdb.md) for version and reconnection settings
- [Authentication](/docs/reference/php/v2/concepts/authentication.md) for handling sign-in failures