Errors

The SDK defines specific error classes for different failure scenarios. All error classes extend the base SurrealError class, allowing you to catch and handle specific error types with isinstance checks.

Source: errors.py

Base Error

`SurrealError`

Base class for every error raised by the SurrealDB Python SDK. Extends Python's built-in Exception.

from surrealdb import SurrealError

try:
    result = db.select("users")
except SurrealError as e:
    print("SDK error:", e)

Server Errors

Server errors originate from the SurrealDB server and carry structured information about the failure. All server errors extend ServerError.

`ServerError`

Extends: SurrealError

Error received from the SurrealDB server with structured kind, details, and cause chain.

Properties

Property	Type	Description
`kind`	`str`	The structured error kind (e.g. `"NotAllowed"`, `"NotFound"`). Match against `ErrorKind` constants.
`code`	`int`	Legacy JSON-RPC error code. `0` when unavailable.
`details`	`dict[str, Any] \| None`	Kind-specific structured details. `None` when not provided.
`server_cause`	`ServerError \| None`	The underlying server error in the cause chain, if any.

Methods

`.has_kind()`

Check if this error or any cause in the chain matches the given kind.

has_kind(kind: str) -> bool

from surrealdb import ErrorKind

try:
    db.query("INVALID")
except ServerError as e:
    if e.has_kind(ErrorKind.VALIDATION):
        print("Validation error")

`.find_cause()`

Find the first error in the cause chain matching the given kind.

find_cause(kind: str) -> ServerError | None

try:
    db.signin({"username": "user", "password": "wrong"})
except ServerError as e:
    auth_cause = e.find_cause(ErrorKind.NOT_ALLOWED)
    if auth_cause:
        print("Auth failure:", auth_cause)

`ValidationError`

Extends: ServerError

Validation failure such as parse errors, invalid request parameters, or bad input.

Properties:

Property	Type	Description
`is_parse_error`	`bool`	Whether this is a query parse error
`parameter_name`	`str \\| None`	The invalid parameter name, if applicable

`ConfigurationError`

Extends: ServerError

Feature or configuration not supported, such as live queries or GraphQL.

Properties:

Property	Type	Description
`is_live_query_not_supported`	`bool`	Whether live queries are not supported

`ThrownError`

Extends: ServerError

User-thrown error via the THROW statement in SurrealQL.

`QueryError`

Extends: ServerError

Query execution failure such as timeout, cancellation, or not executed.

Properties:

Property	Type	Description
`is_not_executed`	`bool`	Whether the query was not executed
`is_timed_out`	`bool`	Whether the query timed out
`is_cancelled`	`bool`	Whether the query was cancelled
`timeout`	`dict[str, Any] \\| None`	The timeout duration as `{"secs": ..., "nanos": ...}`

`SerializationError`

Extends: ServerError

Serialization or deserialization failure.

Properties:

Property	Type	Description
`is_deserialization`	`bool`	Whether this is a deserialization error

`NotAllowedError`

Extends: ServerError

Permission denied, method not allowed, or function/scripting blocked.

Properties:

Property	Type	Description
`is_token_expired`	`bool`	Whether the authentication token has expired
`is_invalid_auth`	`bool`	Whether the authentication credentials are invalid
`is_scripting_blocked`	`bool`	Whether scripting is blocked
`method_name`	`str \\| None`	The disallowed method name
`function_name`	`str \\| None`	The disallowed function name
`target_name`	`str \\| None`	The disallowed target name

from surrealdb import NotAllowedError

try:
    db.signin({"username": "user", "password": "wrong"})
except NotAllowedError as e:
    if e.is_token_expired:
        print("Token expired, re-authenticate")
    elif e.is_invalid_auth:
        print("Invalid credentials")

`NotFoundError`

Extends: ServerError

Resource not found such as table, record, namespace, or method.

Properties:

Property	Type	Description
`table_name`	`str \\| None`	The missing table name
`record_id`	`str \\| None`	The missing record ID
`method_name`	`str \\| None`	The missing method name
`namespace_name`	`str \\| None`	The missing namespace name
`database_name`	`str \\| None`	The missing database name
`session_id`	`str \\| None`	The missing session ID

`AlreadyExistsError`

Extends: ServerError

Duplicate resource such as record, table, or namespace.

Properties:

Property	Type	Description
`record_id`	`str \\| None`	The duplicate record ID
`table_name`	`str \\| None`	The duplicate table name
`session_id`	`str \\| None`	The duplicate session ID
`namespace_name`	`str \\| None`	The duplicate namespace name
`database_name`	`str \\| None`	The duplicate database name

`InternalError`

Extends: ServerError

Internal or unexpected server error. Used as a fallback when the error kind is not recognized.

SDK-Side Errors

These errors originate from the SDK itself, not the server.

`ConnectionUnavailableError`

Extends: SurrealError

Thrown when attempting an operation without an active connection.

from surrealdb import Surreal, ConnectionUnavailableError

db = Surreal("ws://localhost:8000")

try:
    db.select("users")
except ConnectionUnavailableError:
    print("Not connected to database")

`UnsupportedEngineError`

Extends: SurrealError

Thrown when the URL protocol is not supported.

Properties:

Property	Type	Description
`url`	`str`	The unsupported URL

from surrealdb import Surreal, UnsupportedEngineError

try:
    db = Surreal("ftp://localhost:8000")
except UnsupportedEngineError as e:
    print(f"Unsupported protocol: {e.url}")

`UnsupportedFeatureError`

Extends: SurrealError

Thrown when a feature is not supported by the current connection type. For example, sessions and transactions require a WebSocket connection.

from surrealdb import AsyncSurreal, UnsupportedFeatureError

db = AsyncSurreal("http://localhost:8000")
await db.connect()

try:
    session = await db.new_session()
except UnsupportedFeatureError:
    print("Sessions require a WebSocket connection")

`UnexpectedResponseError`

Extends: SurrealError

Thrown when the server returns an unexpected response format.

`InvalidRecordIdError`

Extends: SurrealError

Thrown when a RecordID string could not be parsed.

`InvalidDurationError`

Extends: SurrealError

Thrown when a Duration string could not be parsed.

`InvalidGeometryError`

Extends: SurrealError

Thrown when geometry data is invalid.

`InvalidTableError`

Extends: SurrealError

Thrown when a table or record ID string is invalid.

Error Kind Constants

`ErrorKind`

Known error kinds returned by the SurrealDB server. Use these constants for matching against ServerError.kind.

from surrealdb import ErrorKind

Constant	Value
`ErrorKind.VALIDATION`	`"Validation"`
`ErrorKind.CONFIGURATION`	`"Configuration"`
`ErrorKind.THROWN`	`"Thrown"`
`ErrorKind.QUERY`	`"Query"`
`ErrorKind.SERIALIZATION`	`"Serialization"`
`ErrorKind.NOT_ALLOWED`	`"NotAllowed"`
`ErrorKind.NOT_FOUND`	`"NotFound"`
`ErrorKind.ALREADY_EXISTS`	`"AlreadyExists"`
`ErrorKind.CONNECTION`	`"Connection"`
`ErrorKind.INTERNAL`	`"Internal"`

Detail Kind Constants

Each server error kind has associated detail kind constants for more specific matching.

Class	Constants
`AuthDetailKind`	`TOKEN_EXPIRED`, `SESSION_EXPIRED`, `INVALID_AUTH`, `UNEXPECTED_AUTH`, `MISSING_USER_OR_PASS`, `NO_SIGNIN_TARGET`, `INVALID_PASS`, `TOKEN_MAKING_FAILED`, `INVALID_SIGNUP`, `INVALID_ROLE`, `NOT_ALLOWED`
`ValidationDetailKind`	`PARSE`, `INVALID_REQUEST`, `INVALID_PARAMS`, `NAMESPACE_EMPTY`, `DATABASE_EMPTY`, `INVALID_PARAMETER`, `INVALID_CONTENT`, `INVALID_MERGE`
`ConfigurationDetailKind`	`LIVE_QUERY_NOT_SUPPORTED`, `BAD_LIVE_QUERY_CONFIG`, `BAD_GRAPHQL_CONFIG`
`QueryDetailKind`	`NOT_EXECUTED`, `TIMED_OUT`, `CANCELLED`
`SerializationDetailKind`	`SERIALIZATION`, `DESERIALIZATION`
`NotAllowedDetailKind`	`SCRIPTING`, `AUTH`, `METHOD`, `FUNCTION`, `TARGET`
`NotFoundDetailKind`	`METHOD`, `SESSION`, `TABLE`, `RECORD`, `NAMESPACE`, `DATABASE`, `TRANSACTION`
`AlreadyExistsDetailKind`	`SESSION`, `TABLE`, `RECORD`, `NAMESPACE`, `DATABASE`
`ConnectionDetailKind`	`UNINITIALISED`, `ALREADY_CONNECTED`

Errors

Base Error

SurrealError

Server Errors

ServerError

Properties

Methods

.has_kind()

.find_cause()

ValidationError

ConfigurationError

ThrownError

QueryError

SerializationError

NotAllowedError

NotFoundError

AlreadyExistsError

InternalError

SDK-Side Errors

ConnectionUnavailableError

UnsupportedEngineError

UnsupportedFeatureError

UnexpectedResponseError

InvalidRecordIdError

InvalidDurationError

InvalidGeometryError

InvalidTableError

Error Kind Constants

ErrorKind

Detail Kind Constants

See Also

`SurrealError`

`ServerError`

`.has_kind()`

`.find_cause()`

`ValidationError`

`ConfigurationError`

`ThrownError`

`QueryError`

`SerializationError`

`NotAllowedError`

`NotFoundError`

`AlreadyExistsError`

`InternalError`

`ConnectionUnavailableError`

`UnsupportedEngineError`

`UnsupportedFeatureError`

`UnexpectedResponseError`

`InvalidRecordIdError`

`InvalidDurationError`

`InvalidGeometryError`

`InvalidTableError`

`ErrorKind`