Skip to content
surrealdb.js

Errors

Introduction

Some error objects may have a .cause property. In most cases, this is of type unknown, and its value may change without notice in the future.

General 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, inherited classes with specific meanings are usually thrown. It’s recommended to use this for easily classifying errors caught with try-catch blocks to determine if they originated from this SDK.

Properties

.name: "SurrealError"
The error name.
.message
The error message.
.stack
A stack trace may be recorded.
.cause
The cause or context of the error may be set.

SurrealTypeError

Extends: SurrealError

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

Properties

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

Solution

Trace the stack trace to find the cause of the unexpected data type.

SurrealValueError

Extends: SurrealError

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

Properties

.name: "SurrealValueError"
The error name.
.expected
The expected data type.
.actual
The actual value.

Solution

Trace the stack trace to find the cause of the unexpected data type.

SurrealAggregateError

Extends: SurrealError

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

Properties

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

CircularReferenceError

Extends: 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 contain itself.

Properties

.name: "CircularReferenceError"
The error name.
.reference: unknown
The value where the circular reference occurred.

For example, this error will be 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

Solution

This is a general error that can be thrown outside of the toSurql function. Carefully debug your object to ensure that it does not contain itself.

NumberRangeError

Extends: SurrealError

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

Properties

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

Solution

Trace the stack trace to find the cause of the unexpected data type.

UnsupportedRuntimeError

Extends: SurrealError

This error is thrown when an unsupported runtime is detected.

Properties

.name: "UnsupportedRuntimeError"
The error name.

Solution

Either do not use that runtime or use a polyfill and test thoroughly.

UnreachableError

Extends: SurrealError

This error is thrown when unreachable code is reached. If this error is thrown, you have likely encountered a bug in this SDK.

Properties

.name: "UnreachableError"
The error name.

Solution

You can raise this issue at the following URL:

https://github.com/tai-kun/surrealdb.js/issues

Client Errors

CircularEngineReferenceError

Extends: CircularReferenceError

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

Properties

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

For example, this error will be thrown in the following case:

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


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 example above, a circular reference error is thrown because the https protocol engine attempts to use the engine configured for http, while the http protocol engine attempts to use the engine configured for https.

Solution

Instead of setting a string-specified protocol name to the value of another protocol name, replace it with the concrete implementation for creating the engine:

import { initSurreal } from "@tai-kun/surrealdb";
import HttpEngine from "@tai-kun/surrealdb/http-engine";


const { Surreal } = initSurreal({
  engines: {
    http: "https",
    http: config => new HttpEngine({
      ...config,
      // fetch: <your custom fetch function>
    }),
    https: "http",
  },
  // ...
});

EngineNotFoundError

Extends: SurrealError

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

Properties

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

For example, this error will be thrown in the following case:

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


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


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

Solution

Check the engines property to see if an engine can be created for the protocol of the target endpoint.

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


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

ConnectionConflictError

Extends: SurrealError

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

Properties

.name: "ConnectionConflictError"
The error name.
.endpoint1: string
The already connected endpoint.
.endpoint2: string
The other endpoint. 
import { Surreal } from "@tai-kun/surrealdb";


await using db = new Surreal();


await db.connect("ws://localhost:8000");
await db.connect("ws://localhost:1129"); // throws ConnectionConflictError: An attempt was made to connect to ws://localhost:1129/rpc while ws://localhost:8000/rpc was already connected.

The .connect method appends /rpc to the URL path if it is not already present. Therefore, if one endpoint’s URL path ends with /rpc, it may not result in an error despite appearances:

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


await using db = new Surreal();


await db.connect("http://localhost:8000");
await db.connect("http://localhost:8000/rpc"); // OK!
import { Surreal } from "@tai-kun/surrealdb";


await using db = new Surreal();


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

Solution

You can connect to any endpoint by calling the .close method before calling the .connect method.

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


await using db = new Surreal();


await db.connect("http://localhost:8000");
await db.close();
await db.connect("http://localhost:11298");

MissingNamespaceError

Extends: SurrealError

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

Properties

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

For example, this error will be thrown in the following case:

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


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.

Solution

Select a namespace when selecting a database.

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


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


await db.use({
  namespace: "example",
  database: "example",
});

RpcResponseError

Extends: SurrealError

This error is thrown when the RPC response indicates an error. This means SurrealDB could not process the RPC request, despite successful communication and response body decoding.

Properties

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

Solution

Various causes are possible, but it’s likely that the SurrealDB version this SDK is compatible with and the version processing the RPC request differ.

QueryFailedError

Extends: SurrealAggregateError

This error is thrown when a query fails.

Properties

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

For example, this error will be 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)

Solution

Verify the correctness of the SurrelQL syntax.

Closed

Extends: SurrealError

Indicates that the connection has been forcibly closed.

Properties

.name: "Closed"
The error name.

For example, you get 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); // Closed
      reject();
    })


    // ...
  });
});


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

Engine Errors

EngineError

Extends: SurrealError

Indicates an error originating from the engine. Dispatched via event listeners.

Properties

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

HttpEngineError

Extends: EngineError

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

Properties

.name: "HttpEngineError"
The error name.

WebSocketEngineError

Extends: EngineError

Indicates an error originating from the WebSocket engine. Used when failing to parse the response body before finding the RPC request ID, receiving an error event from the WebSocket object, or closing the WebSocket connection.

This SDK uses 315x as a custom status code. This range is unassigned in the IANA registry.

Properties

.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 a WebSocket[^1] instance.
  • 3151: Indicates that an error occurred within the “open” event handler registered by the WebSocket engine. This is most often a StateTransitionError during a transition from connecting to connected state.
  • 3152: Indicates that an error occurred within the “message” event handler registered by the WebSocket engine. Various causes are possible, but it is likely that a ServerResponseError or RpcResponseError was thrown within the event handler. This is often caused by an invalid RPC parameter request, which causes the calling method to (by default) timeout after 5 seconds. In SurrealDB versions before v2.0.2, timeouts were more broadly possible.
  • 3153: Indicates failure to send or receive a ping. This may be a temporary error; however, consistent receipt of this error indicates a connection problem.
  • 3154: Indicates that an error occurred within the “close” event handler registered by the WebSocket engine. This is most often a StateTransitionError during a transition from disconnecting to disconnected state.
The following status codes are excluded from the above. They are not treated as errors by this SDK:
  • 1000: Normal closure.
  • 1001: Going away is common.
  • 1004: Reserved.
  • 1005: Reserved.
  • 1006: Reserved.
  • 1015: Reserved.

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

Solution

1002,1003,1007…1011,1014,3150,3151,3154
There is likely no automatic recovery from these status codes. You need to correct the runtime, SurrealDB settings, or hardcoded implementation.
3152
Check if the arguments passed to the method (i.e., the content of the RPC request) are correct.
1012,1013,3153
You may be able to recover automatically using the experimental feature autoReconnect().

StateTransitionError

Extends: SurrealAggregateError

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

Properties

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

For example, this error will be thrown in the following case:

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


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

Extends: SurrealError

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

Properties

.name: "ConnectionUnavailableError"
The error name.

ServerResponseError

Extends: SurrealError

This error is thrown when the response cannot be parsed as an RPC response. This is different from RpcResponseError.

Properties

.name: "ServerResponseError"
The error name.

Solution

This error should not normally occur, but if it does, it is likely that the SurrealDB version this SDK is compatible with and the version processing the RPC request differ.

CBOR Errors

CborError

Extends: SurrealError

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

Properties

.name: "CborError"
The error name.

CborWellFormednessError

Extends: CborError

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

See RFC8949 Appendix F “Well-Formedness Errors and Examples”.

Properties

.name: "CborWellFormednessError"
The error name.

CborTooMuchDataError

Extends: CborWellFormednessError

Indicates that there are unconsumed input bytes remaining.

RFC8949

Properties

.name: "CborTooMuchDataError"
The error name.

Solution

Check if the byte array to be decoded is in the correct CBOR format.

CborTooLittleDataError

Extends: CborWellFormednessError

Indicates that the input bytes are incomplete.

RFC8949

Properties

.name: "CborTooLittleDataError"
The error name.

Solution

Check if the byte array to be decoded is in the correct CBOR format.

CborSyntaxError

Extends: CborWellFormednessError

Indicates that the input bytes do not match the CBOR encoding format.

RFC8949

Properties

.name: "CborSyntaxError"
The error name.

Solution

Check if the byte array to be decoded is in the correct CBOR format.

CborMaxDepthReachedError

Extends: CborError

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

Properties

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

Solution

Either relax the limit of the optional .maxDepth or restructure the data so that the object nesting is shallower.

import CborFormatter from "@tai-kun/surrealdb/cbor-formatter";


const cborFormatter = new CborFormatter({
  encode: {
    maxDepth: 1024,
  },
  decode: {
    maxDepth: 1024,
  },
  // ...
})

CborUnsafeMapKeyError

Extends: CborError

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

Properties

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

JSON Errors

JsonError

Extends: SurrealError

This is the base class for all errors explicitly thrown by @tai-kun/surrealdb/json the JSON formatter.

Properties

.name: "JsonError"
The error name.

JsonUnsafeMapKeyError

Extends: JsonError

This error is thrown when an unsafe map key is encountered during JSON decoding.

Properties

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