跳转到内容
surrealdb.js

错误

SurrealError

SurrealError 是此 SDK 明确抛出的几乎所有错误对象的基类。此类继承自 JavaScript 的 Error 类。此错误对象很少单独抛出，通常抛出的是继承自它的具有特殊含义的错误对象。建议使用 try-catch 语句捕获此错误，以便轻松区分此 SDK 明确抛出的错误。

.name: "SurrealError"
错误名称。
.message
错误消息。
.stack
可能记录了堆栈跟踪。
.cause
可能设置了导致错误的原因或上下文。

SurrealTypeError

继承自: SurrealError

当输入值或其他验证失败时抛出此错误。

.name: "SurrealTypeError"
错误名称。
.expected
期望的数据类型。
.actual
实际值的字符串表示。

SurrealAggregateError

继承自: SurrealError

这是多个错误或错误消息的集合。

.name: "SurrealAggregateError"
错误名称。
.cause: unknown[]
数组的每个元素包含错误或错误消息等。

CircularReferenceError

继承自: SurrealError

当检测到循环引用时抛出此错误。主要是在将 JavaScript 值转换为其他格式的过程中，检测到父对象与子对象相同时抛出。

.name: "CircularReferenceError"
错误名称。

例如，在以下情况下会抛出此错误：

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

继承自: SurrealError

当数值超出范围时抛出此错误。

.name: "NumberRangeError"
错误名称。
.range
期望的范围。
.actual
实际值。
.integer
如果为 true，则期望整数。

UnsupportedRuntimeError

继承自: SurrealError

当检测到使用不受支持的运行时环境时抛出此错误。

.name: "UnsupportedRuntimeError"
错误名称。

UnreachableError

继承自: SurrealError

当到达不可达代码时抛出此错误。如果抛出此错误，则可能遇到了此 SDK 的错误。

.name: "UnreachableError"
错误名称。

CircularEngineReferenceError

继承自: CircularReferenceError

当连接数据库时，如果引擎之间发生循环引用，则抛出此错误。

.name: "CircularEngineReferenceError"
错误名称。
.seen: string[]
发生循环引用之前经过的协议名称列表。

例如，在以下情况下会抛出此错误：

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

上面的例子中，尽管 https 协议的引擎指定使用 http 引擎，但 http 协议的引擎又尝试使用 https 引擎，从而导致循环引用错误。

EngineNotFoundError

继承自: SurrealError

当尝试使用未设置引擎的协议进行连接时抛出此错误。

.name: "EngineNotFoundError"
错误名称。
.protocol: string
目标协议名称。

例如，在以下情况下会抛出此错误：

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

继承自: SurrealError

当客户端尝试同时连接多个端点时抛出此错误。

.name: "ConnectionConflictError"
错误名称。
.endpoint1: string
一个端点。
.endpoint2: string
另一个端点。 
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.

.connect 方法如果传入的 URL 路径不以 /rpc 结尾，则会在末尾添加 /rpc。因此，如果一个端点的 URL 路径以 /rpc 结尾，则可能会出现与预期不符的情况：

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

继承自: SurrealError

当 SDK 尝试同时切换到多个不同的命名空间时抛出此错误。

.name: "NamespaceConflictError"
错误名称。
.namespace1: string
一个命名空间。
.namespace2: string
另一个命名空间。

例如，在以下情况下会抛出此错误：

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

继承自: SurrealError

当 SDK 尝试同时切换到多个不同的数据库时抛出此错误。

.name: "DatabaseConflictError"
错误名称。
.database1: string
一个数据库。
.database2: string
另一个数据库。

例如，在以下情况下会抛出此错误：

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

继承自: SurrealError

当在选择数据库之前没有选择命名空间时抛出此错误。或者，当在已选择数据库的情况下尝试取消选择命名空间时也会抛出此错误。

.name: "MissingNamespaceError"
错误名称。
.database: string
数据库名称。

例如，在以下情况下会抛出此错误：

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

继承自: SurrealError

当 RPC 响应指示错误时抛出此错误。连接的协议通信和响应体的解码没有问题，但这意味着 SurrealDB 无法处理 RPC 请求。

.name: "RpcResponseError"
错误名称。
.id?: string
用于标识 RPC 请求的 ID。ID 始终以 <方法名>_ 开头。
.code: number
SurrealDB 的文档中未明确说明，但可能是 JSON-RPC 的错误代码。

QueryFailedError

继承自: SurrealAggregateError

当查询失败时抛出此错误。

.name: "QueryFailedError"
错误名称。
.cause: string[]
错误列表。

例如，在以下情况下会抛出此错误：

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

继承自: SurrealError

此错误表示连接已被强制终止。

.name: "Disconnected"
错误名称。

例如，在以下情况下会获得此错误：

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

继承自: SurrealError

这表示这是一个由引擎引起的错误。通过事件监听器发送。

.name: "EngineError"
错误名称。
.fatal: boolean | undefined
指示此错误是否为致命错误。

HttpEngineError

继承自: EngineError

这表示这是一个由 HTTP 引擎引起的错误。目前仅定义，未使用。

.name: "HttpEngineError"
错误名称。

WebSocketEngineError

继承自: EngineError

这表示这是一个由 WebSocket 引擎引起的错误。在解析响应体失败之前找不到标识 RPC 请求的 ID，或者从 WebSocket 对象接收到错误事件，或者关闭 WebSocket 连接时使用。

.name: "WebSocketEngineError"
错误名称。
.code: number
以下状态代码之一：
  • 1000~1015: MDN 参考
  • 3150: 表示从 WebSocket[^1] 实例接收到 “error” 事件。
  • 3151: 表示在 WebSocket 引擎注册的 “open” 事件处理程序中发生错误。这几乎总是因为在从连接中状态到连接状态的转换过程中发生了 StateTransitionError。
  • 3152: 表示在 WebSocket 引擎注册的 “message” 事件处理程序中发生错误。可能有多种原因，但很可能是事件处理程序中抛出了 ResponseError 或 RpcResponseError。追溯到根源，可能是因为在 .query() 方法中请求了语法错误的 SurrealQL 自定义查询，或者使用无效的 RPC 参数进行了请求。在这种情况下，RPC 的调用方法（默认情况下）会在 5 秒后超时并失败。
  • 3153: 表示 ping 的发送或接收失败。这可能是暂时的错误，但如果持续收到此错误，则可能表示连接无法维持。
  • 3154: 表示在 WebSocket 引擎注册的 “close” 事件处理程序中发生错误。这几乎总是因为在从断开连接状态到断开状态的转换过程中发生了 StateTransitionError。
此外，排除以下状态代码，SDK 不将其视为错误：
  • 1000: 正常断开连接。
  • 1001: 早期断开连接很常见。
  • 1004: 保留。
  • 1005: 保留。
  • 1006: 保留。
  • 1015: 保留。

^1: WebSocket 可能是运行时在全局变量中定义的类，也可能是 ws SDK 的类。

StateTransitionError

继承自: SurrealAggregateError

当状态转换期间事件监听器的执行失败时抛出此错误。

.name: "StateTransitionError"
错误名称。
.from: number
状态转换开始时的状态。
.to: number
目标状态。
.fallback: number
状态转换失败时的备用目标状态。如果与 .to 相同，则表示强制进行了转换。

例如，在以下情况下会抛出此错误：

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

继承自: SurrealError

当尝试在未连接状态下发送 RPC 请求时抛出此错误。

.name: "ConnectionUnavailableError"
错误名称。

ResponseError

继承自: SurrealError

当无法将响应解析为 PRC 响应时抛出此错误。与 RpcResponseError 不同。

.name: "ResponseError"
错误名称。

CborError

继承自: SurrealError

这是 @tai-kun/surrealdb/cbor 明确抛出的所有与 CBOR 相关的错误的基类。它不会直接抛出。

.name: "CborError"
错误名称。

CborWellFormednessError

继承自: CborError

这是 @tai-kun/surrealdb/cbor 明确抛出的所有与 CBOR 解码相关的错误的基类。它不会直接抛出。

请参考 RFC8949 附录 F 中的“Well-Formedness Errors and Examples”。

.name: "CborWellFormednessError"
错误名称。

CborTooMuchDataError

继承自: CborWellFormednessError

这表示存在未使用的输入字节。

RFC8949

.name: "CborTooMuchDataError"
错误名称。

CborTooLittleDataError

继承自: CborWellFormednessError

这表示输入字节不完整。

RFC8949

.name: "CborTooLittleDataError"
错误名称。

CborSyntaxError

继承自: CborWellFormednessError

这表示输入字节与 CBOR 编码格式不匹配。

RFC8949

.name: "CborSyntaxError"
错误名称。

CborMaxDepthReachedError

继承自: CborError

当 CBOR 编码或解码时 JavaScript 对象的深度达到最大值时抛出此错误。每次进入对象或数组时，深度都会增加 1。

.name: "CborMaxDepthReachedError"
错误名称。
.maxDepth: number
最大深度。

CborUnsafeMapKeyError

继承自: CborError

当 CBOR 编码或解码时发现不安全的映射键时抛出此错误。

.name: "CborUnsafeMapKeyError"
错误名称。
.key: unknown
被判定为不安全的映射键。