Error handling | Mojo SDK

The Mojo SDK reports failures in two places: on the RpcResponse for errors the server returns, and as raised Mojo Error values for transport and protocol failures.

The error kinds, wire codes and structured shape behind these are documented once in Errors, which applies to every SDK and protocol.

Response errors

A query that the server rejects comes back as an RpcResponse with is_error() true. Read the code and message with error_code() and error_message().

var resp = client.query("SELECT * FROM person WHERE;")  # invalid

if resp.is_error():
    print("code:", resp.error_code().value())
    print("message:", resp.error_message().value())

Raised errors

Transport and protocol failures raise Mojo Error values whose messages carry a typed prefix from SurrealErrorKind:

ConnectionError(-1): tcp connect failed to localhost:8000
ProtocolError(-1): http response has no header terminator
UnsupportedFeatureError(-1): websocket transport is not available; use the http engine

The kinds live in surrealdb.errors.SurrealErrorKind and cover connection, protocol, RPC, query, auth, decode, engine, serialisation, live-query, timeout, and unsupported-feature failures.

The matching helper functions (fail_connection, fail_protocol, fail_unsupported_feature, and the rest) are exported, so you can raise SDK-shaped errors from your own code.

from surrealdb import fail_connection

fn dial() raises:
    fail_connection("tcp connect failed to localhost:8000")

Unsupported features

Before issuing a request that needs a stateful feature, the client checks the active transport's capabilities(). If the transport does not support the feature, the SDK raises an UnsupportedFeatureError rather than sending a request the server would reject. This is how an HTTP-only connection responds to a live query or a session request.