Skip to content
surrealdb.js

Errors

SurrealError

SurrealError is the base class inherited by almost all error objects explicitly thrown by this SDK. This class inherits from JavaScript’s Error class. This error object is rarely thrown directly; instead, inheriting classes with specific meanings are typically thrown. It is recommended to use this for easy classification of errors caught using try-catch statements to determine if they were explicitly thrown by this SDK.

.name: "SurrealError"
The error name.
.message
The error message.
.stack
May contain a stack trace.
.cause
May contain the cause or context of the error.

SurrealTypeError

Inherits from: SurrealError

This error is thrown when input values or other validations fail.

.name: "SurrealTypeError"
The error name.
.expected
The expected data type.
.actual
A string representation of the actual value.

SurrealAggregateError

Inherits from: SurrealError

This is an error that aggregates multiple errors or error messages.

.name: "SurrealAggregateError"
The error name.
.cause: unknown[]
Each element of the array contains an error or error message.

CircularReferenceError

Inherits from: SurrealError

This error is thrown when a circular reference is detected. This primarily occurs during the conversion of JavaScript values to other formats when an object is found to refer back to its parent object.

.name: "CircularReferenceError"
The error name.

For example, this error is thrown in the following case:

import { toSurql } from "@tai-kun/surrealdb/utils";


const a = {};
a.a = a;


console.log(a); // <ref *1> { a: [Circular *1] }


toSurql(a); // throws CircularReferenceError

NumberRangeError

Inherits from: SurrealError

This error is thrown when a number is outside the allowed range.

.name: "NumberRangeError"
The error name.
.range
The expected range.
.actual
The actual value.
.integer
If true, an integer is expected.

UnsupportedRuntimeError

Inherits from: SurrealError

This error is thrown if an unsupported runtime is detected.

.name: "UnsupportedRuntimeError"
The error name.

UnreachableError

Inherits from: SurrealError

This error is thrown if unreachable code is reached. If this error is thrown, it likely indicates a bug in this SDK.

.name: "UnreachableError"
The error name.

CircularEngineReferenceError

Inherits from: CircularReferenceError

This error is thrown when a circular reference occurs between engines when connecting to the database.

.name: "CircularEngineReferenceError"
The error name.
.seen: string[]
A list of protocol names traversed before the circular reference occurred.

For example, this error is thrown in the following case:

const { Surreal } = initSurreal({
  engines: {
    http: "https",
    https: "http",
  },
  // ...
});


await using db = new Surreal();
await db.connect("https://localhost:8000"); // throws CircularEngineReferenceError: Circular engine reference: http,https

In the above example, the https engine is configured to use the http engine, but the http engine attempts to use the https engine, resulting in a circular reference error.

EngineNotFoundError

Inherits from: SurrealError

This error is thrown when attempting to connect using a protocol for which no engine is configured.

.name: "EngineNotFoundError"
The error name.
.protocol: string
The protocol name of the connection target.

For example, this error is thrown in the following case:

const { Surreal } = initSurreal({
  engines: {
    http: config => new HttpEngine(config),
  },
  // ...
});


await using db = new Surreal();
await db.connect("https://localhost:8000"); // throws EngineNotFoundError: No https protocol engine found.

ConnectionConflictError

Inherits from: SurrealError

This error is thrown when a client attempts to connect to multiple endpoints simultaneously.

.name: "ConnectionConflictError"
The error name.
.endpoint1: string
One of the endpoints.
.endpoint2: string
The other endpoint. 
await using db = new Surreal();


await db.connect("http://localhost:8000");
await db.connect("http://localhost:11298"); // throws ConnectionConflictError: Connection conflict between http://localhost:8000/rpc and http://localhost:11298/rpc.

The .connect method appends /rpc to the URL if it’s not already present. Therefore, if one endpoint’s URL already ends with /rpc, it might not throw an error as expected:

await using db = new Surreal();


await db.connect("http://localhost:8000");
await db.connect("http://localhost:8000/rpc"); // OK!
await using db = new Surreal();


await db.connect("http://localhost:8000/rpc");
await db.connect("http://localhost:8000"); // OK!

NamespaceConflictError

Inherits from: SurrealError

This error is thrown when the SDK attempts to switch to multiple different namespaces simultaneously.

.name: "NamespaceConflictError"
The error name.
.namespace1: string
One of the namespaces.
.namespace2: string
The other namespace.

For example, this error is thrown in the following case:

await using db = new Surreal();


await db.connect("http://localhost:8000");
await db.signin({ user: "root", pass: "root" });
await Promise.all([
  db.use({ namespace: "foo" }),
  db.use({ namespace: "bar" }),
]);

DatabaseConflictError

Inherits from: SurrealError

This error is thrown when the SDK attempts to switch to multiple different databases simultaneously.

.name: "DatabaseConflictError"
The error name.
.database1: string
One of the databases.
.database2: string
The other database.

For example, this error is thrown in the following case:

await using db = new Surreal();


await db.connect("http://localhost:8000");
await db.signin({ user: "root", pass: "root" });
await Promise.all([
  db.use({ namespace: "baz", database: "foo" }),
  db.use({ namespace: "baz", database: "bar" }),
]);

MissingNamespaceError

Inherits from: SurrealError

This error is thrown if a namespace is not selected before selecting a database, or if an attempt is made to unselect a namespace while a database is selected.

.name: "MissingNamespaceError"
The error name.
.database: string
The database name.

For example, this error is thrown in the following case:

await using db = new Surreal();
await db.connect("http://localhost:8000");


await db.use({ database: "example" }); // throws MissingNamespaceError: The namespace must be specified before the database.

RpcResponseError

Inherits from: SurrealError

This error is thrown when the RPC response indicates an error. There is no problem with communication or decoding of the response body based on the connected protocol, but it means that SurrealDB could not process the RPC request.

.name: "RpcResponseError"
The error name.
.id?: string
The ID identifying the RPC request. The ID always starts with <method name>_.
.code: number
Not explicitly documented in the SurrealDB documentation, but likely a JSON-RPC error code.

QueryFailedError

Inherits from: SurrealAggregateError

This error is thrown when a query fails.

.name: "QueryFailedError"
The error name.
.cause: string[]
A list of errors.

For example, this error is thrown in the following case:

await using db = new Surreal();
await db.connect("http://localhost:8000");


await db.query("OUTPUT 'Hello'"); // throws QueryFailedError: Query failed with 1 error(s)

Disconnected

Inherits from: SurrealError

This error indicates that the connection has been forcibly terminated.

.name: "Disconnected"
The error name.

For example, you will receive this error in the following case:

const db = new Surreal();


db.on("<event_name>", ({ signal }) => {
  return new Promise((resolve, reject) => {
    signal.addEventListener("abort", function() {
      console.error(this.reason); // Disconnected
      reject();
    })


    // ...
  });
});


await db.disconnect({ force: true });

EngineError

Inherits from: SurrealError

This indicates an error originating from the engine. It is dispatched via an event listener.

.name: "EngineError"
The error name.
.fatal: boolean | undefined
Indicates whether this error is fatal.

HttpEngineError

Inherits from: EngineError

This indicates an error originating from the HTTP engine. Currently defined but not used.

.name: "HttpEngineError"
The error name.

WebSocketEngineError

Inherits from: EngineError

This indicates an error originating from the WebSocket engine. It is used when response body parsing fails before an RPC request ID can be found, when an error event is received from the WebSocket object, or when the WebSocket connection is closed.

.name: "WebSocketEngineError"
The error name.
.code: number
One of the following status codes:
  • 1000~1015: MDN Reference
  • 3150: Indicates that an “error” event was received from the WebSocket[^1] instance.
  • 3151: Indicates that an error occurred in the “open” event handler registered by the WebSocket engine. This is usually a StateTransitionError occurring during a transition from the connecting state to the connected state.
  • 3152: Indicates that an error occurred in the “message” event handler registered by the WebSocket engine. Many causes are possible, but it is likely that a ResponseError or RpcResponseError was thrown in the event handler. Tracing back the cause, it might be due to a request with incorrect SurrealQL custom query syntax in the .query() method, or a request with invalid RPC parameters. In that case, the RPC call’s method (by default) will timeout after 5 seconds and fail.
  • 3153: Indicates a failure in sending or receiving a ping. This may be a temporary error, but if you continue to receive it, the connection may not be maintained.
  • 3154: Indicates that an error occurred in the “close” event handler registered by the WebSocket engine. This is usually a StateTransitionError that occurred during a transition from the disconnecting state to the disconnected state.
Note: The following status codes are excluded from the above. This SDK does not treat them as errors:
  • 1000: Cleanly disconnected.
  • 1001: Early disconnections are common.
  • 1004: Reserved.
  • 1005: Reserved.
  • 1006: Reserved.
  • 1015: Reserved.

^1: WebSocket may be a class defined in the runtime’s global variables or a class from the ws SDK.

StateTransitionError

Inherits from: SurrealAggregateError

This error is thrown when an event listener fails to execute during a state transition.

.name: "StateTransitionError"
The error name.
.from: number
The state at the start of the transition.
.to: number
The target state of the transition.
.fallback: number
The alternative target state if the state transition failed. If it is the same value as .to, it means that the transition was forced.

For example, this error is thrown in the following case:

import { Surreal } from "@tai-kun/surrealdb";
import { CONNECTING } from "@tai-kun/surrealdb/engine";


await using db = new Surreal();


db.on(CONNECTING, () => {
  throw new Error("Don't let me connect !!!")
});


await db.connect("http://localhost:8000"); // throws ...
// StateTransitionError: The transition from `3` to `0` failed, falling back to `3`.
//     at <stack trace ...> {
//   cause: [
//     Error: Don't let me connect !!!
//         at <stack trace ...>
//   ],
//   from: 3,
//   to: 0,
//   fallback: 3
// }

ConnectionUnavailableError

Inherits from: SurrealError

This error is thrown when attempting to send an RPC request while not connected.

.name: "ConnectionUnavailableError"
The error name.

ResponseError

Inherits from: SurrealError

This error is thrown when a response cannot be parsed as a PRC response. This is different from RpcResponseError.

.name: "ResponseError"
The error name.

CborError

Inherits from: SurrealError

This is the base class for all CBOR-related errors explicitly thrown by @tai-kun/surrealdb/cbor. It is never thrown directly.

.name: "CborError"
The error name.

CborWellFormednessError

Inherits from: CborError

This is the base class for all CBOR decoding-related errors explicitly thrown by @tai-kun/surrealdb/cbor. It is never thrown directly.

See Appendix F, “Well-Formedness Errors and Examples,” in RFC8949: https://datatracker.ietf.org/doc/html/rfc8949#name-well-formedness-errors-and-

.name: "CborWellFormednessError"
The error name.

CborTooMuchDataError

Inherits from: CborWellFormednessError

This indicates that unconsumed input bytes remain.

RFC8949

.name: "CborTooMuchDataError"
The error name.

CborTooLittleDataError

Inherits from: CborWellFormednessError

This indicates that the input bytes are incomplete.

RFC8949

.name: "CborTooLittleDataError"
The error name.

CborSyntaxError

Inherits from: CborWellFormednessError

This indicates that the input bytes do not match the CBOR encoding format.

RFC8949

.name: "CborSyntaxError"
The error name.

CborMaxDepthReachedError

Inherits from: CborError

This error is thrown when the depth of a JavaScript object reaches the maximum value during CBOR encoding or decoding. The depth increases by 1 each time an object or array is entered.

.name: "CborMaxDepthReachedError"
The error name.
.maxDepth: number
The maximum depth.

CborUnsafeMapKeyError

Inherits from: CborError

This error is thrown when an unsafe map key is found during CBOR encoding or decoding.

.name: "CborUnsafeMapKeyError"
The error name.
.key: unknown
The map key determined to be unsafe.