Errors

SurrealError

Abstract base type for all SurrealDB SDK errors.

ServerError <: SurrealError

Abstract supertype for errors that originated server-side (i.e. the SurrealDB engine reported the failure). Mirrors the kind-tagged ServerError hierarchy in surrealdb.js and surrealdb.py — concrete subtypes correspond to the kind field of the wire-protocol error payload.

Concrete subtypes:

• ValidationError — request validation failed
• ConfigurationError — database/namespace/feature misconfiguration
• ThrownError — user THROW statement
• QueryError — SurrealQL parse/execution failure
• SerializationError — wire encode/decode failure
• NotAllowedError — auth/permission denial
• NotFoundError — record/table/namespace not found
• AlreadyExistsError — record already exists
• InternalError — server-side bug

Catch ServerError to handle any server-side failure uniformly; catch a specific subtype for kind-aware handling.

RPCError(code, message)

Represents a JSON-RPC error returned by the SurrealDB server. This includes transport errors, protocol errors, and server-side failures.

Fields:

• code::Int: JSON-RPC numeric error code
• message::String: Human-readable error message from the server

QueryError(message)

A SurrealQL parse or execution failure. Subtype of ServerError.

Fields:

• message::String: Error message describing the query failure
• is_timed_out::Bool: true when the server reports the query timed out
• is_cancelled::Bool: true when the query was cancelled mid-execution

Bare-message constructor is supported for backward compat: QueryError(msg) ≡ QueryError(msg, false, false).

ValidationError(message; parameter_name=nothing, is_parse_error=false)

Request validation failed before the query was executed. Subtype of ServerError.

ConfigurationError(message; is_live_query_not_supported=false)

Database/namespace/feature configuration prevents the operation. Subtype of ServerError.

ThrownError(message)

Result of an explicit user THROW statement in SurrealQL. Subtype of ServerError.

SerializationError(message; is_deserialization=false)

Wire-format encode/decode failure. Subtype of ServerError.

NotAllowedError(message; is_token_expired=false, is_invalid_auth=false, method_name=nothing)

Authentication or authorization denied the request. Subtype of ServerError.

NotFoundError(message; table_name=nothing, record_id=nothing, namespace_name=nothing)

A referenced record, table, or namespace does not exist. Subtype of ServerError.

AlreadyExistsError(message; table_name=nothing, record_id=nothing)

The target record/table already exists and the operation rejects duplicates. Subtype of ServerError.

InternalError(message)

A server-side bug or unexpected condition. Subtype of ServerError.

ConnectionError(message, cause)

Represents a connection-level failure (WebSocket disconnect, timeout, etc.).

Fields:

• message::String: Description of the connection failure
• cause::Union{Exception, Nothing}: Underlying exception that caused the failure, if any

ConnectionUnavailableError(message="No active connection to the database.")

The client is not connected (or has been closed). Distinct from ConnectionError which represents transport-level failures during an attempt; this is raised for "no connection at all" scenarios.

MissingNamespaceDatabaseError()

Thrown when connect(...) (or any operation that selects a server scope) is given exactly one of ns / db — both must be set, or neither. Database selection is namespace-scoped on the server, so a database without a namespace is meaningless. Mirrors the JS SDK's MissingNamespaceDatabaseError (external/sdk-refs/js/.../errors.ts:88).

UnsupportedEngineError(scheme::String)

The URL scheme is not recognised. Mirrors the JS SDK's same-named error.

UnsupportedFeatureError(feature, transport=nothing)

The requested operation is not supported on the current transport (e.g. live queries over HTTP). feature is a Symbol naming the feature; transport optionally names the transport that lacks support.

UnsupportedVersionError(server_version, minimum, maximum)

The connected SurrealDB server reports a version outside the SDK's supported range. Thrown by connect() after the version probe, before any user code sees the client. Mirrors the JS SDK's same-named error.

• server_version is the raw version string the server returned.
• minimum / maximum are the SDK's accepted bounds (strings, semver-compatible).

UnexpectedResponseError(message)

The server returned a response in an unexpected shape. Used when the wire format doesn't match any of the documented response variants.

EmbeddedFFIError(op, message)

A failure originating from the embedded libsurreal FFI layer. Distinct from RPCError (which represents server-side JSON-RPC failures) and ConnectionError (transport-level failures) so callers can distinguish "libsurreal misbehaved" from "the network blinked."

Fields:

• op::String: the FFI operation that failed (e.g. "sr_patch_add", "_self_test_layout")
• message::String: error message — either propagated from the C library or describing the layout/lookup mismatch