컨텐츠로 건너뛰기
surrealdb.js

에러

시작하기

일부 에러 객체에는 .cause 속성이 설정되어 있을 수 있습니다. 대부분의 경우 이는 unknown 형식이며, 값은 추후 예고 없이 변경될 수 있습니다.

일반

SurrealError

SurrealError는 이 SDK가 명시적으로 던지는 대부분의 에러 객체가 상속하는 기본 클래스입니다. 이 클래스는 JavaScript의 Error 클래스를 상속합니다. 이 에러 객체가 단독으로 던져지는 경우는 거의 없으며, 기본적으로는 상속 클래스의 특별한 의미를 가진 에러 객체가 던져집니다. try-catch 구문 등으로 포착된 에러가 이 SDK가 명시적으로 던진 에러인지 여부를 쉽게 분류하기 위해 사용하는 것을 권장합니다.

속성

.name: "SurrealError"
에러 이름입니다.
.message
에러 메시지입니다.
.stack
스택 트레이스가 기록되어 있을 수 있습니다.
.cause
에러가 발생한 원인이나 컨텍스트가 설정될 수 있습니다.

SurrealTypeError

상속원: SurrealError

입력값이나 기타 검증에 실패한 경우 던져지는 에러입니다.

속성

.name: "SurrealTypeError"
에러 이름입니다.
.expected
예상하는 데이터 형식입니다.
.actual
실제 값의 문자열 표현입니다.

해결책

스택 트레이스를 따라 예상하는 데이터 형식이 입력되지 않는 원인을 찾습니다.

SurrealValueError

상속원: SurrealError

입력값이나 기타 검증에 실패한 경우 던져지는 에러입니다.

속성

.name: "SurrealValueError"
에러 이름입니다.
.expected
예상하는 데이터 형식입니다.
.actual
실제 값입니다.

해결책

스택 트레이스를 따라 예상하는 데이터 형식이 입력되지 않는 원인을 찾습니다.

SurrealAggregateError

상속원: SurrealError

여러 에러 또는 에러 메시지가 결합된 에러입니다.

속성

.name: "SurrealAggregateError"
에러 이름입니다.
.cause: unknown[]
배열의 각 요소에 에러 또는 에러 메시지 등이 포함되어 있습니다.

CircularReferenceError

상속원: SurrealError

순환 참조를 감지한 경우 던져지는 에러입니다. 주로 JavaScript 값을 다른 형식으로 변환하는 과정에서 부모 객체와 동일한 객체가 감지된 경우 던져집니다.

속성

.name: "CircularReferenceError"
에러 이름입니다.
.reference: unknown
순환 참조가 발생한 값입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

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


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


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


toSurql(a); // throws CircularReferenceError

해결책

이 에러는 toSurql 함수 이외에도 던져지는 일반적인 에러입니다. 객체 내부에 해당 객체가 포함되어 있지 않은지 신중하게 디버깅해야 합니다.

NumberRangeError

상속원: SurrealError

숫자가 범위를 벗어난 값을 가진 경우 던져지는 에러입니다.

속성

.name: "NumberRangeError"
에러 이름입니다.
.range
예상 범위입니다.
.actual
실제 값입니다.
.integer
true인 경우 정수를 예상합니다.

해결책

스택 트레이스를 따라 예상하는 데이터 형식이 입력되지 않는 원인을 찾습니다.

UnsupportedRuntimeError

상속원: SurrealError

지원되지 않는 런타임을 사용하고 있다고 판단된 경우 던져지는 에러입니다.

속성

.name: "UnsupportedRuntimeError"
에러 이름입니다.

해결책

해당 런타임을 사용하지 않거나, 폴리필을 사용하여 충분히 테스트해야 합니다.

UnreachableError

상속원: SurrealError

도달할 수 없는 코드에 도달한 경우 던져지는 에러입니다. 이 에러가 던져진 경우, 이 SDK의 버그를 만났을 가능성이 높습니다.

속성

.name: "UnreachableError"
에러 이름입니다.

해결책

다음 URL에서 이 문제를 제기할 수 있습니다.

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

클라이언트

CircularEngineReferenceError

상속원: CircularReferenceError

데이터베이스에 연결할 때 엔진 간에 순환 참조가 발생한 경우 던져지는 에러입니다.

속성

.name: "CircularEngineReferenceError"
에러 이름입니다.
.reference: string
순환 참조가 발생한 스키마 이름입니다.
.seen: string[]
순환 참조가 발생하기까지 거친 스키마 이름 목록입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

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

위 예시에서는 https 프로토콜 엔진이 http에 설정된 엔진을 사용하려고 하는데, http 프로토콜 엔진은 다시 https에 설정된 엔진을 사용하려고 하기 때문에 순환 참조 에러가 발생합니다.

해결책

문자열로 지정된 프로토콜 이름을 다른 프로토콜 이름의 값으로 설정하지 않고, 대신 엔진을 생성하는 구체적인 구현으로 대체합니다.

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

상속원: SurrealError

엔진이 설정되지 않은 프로토콜로 연결하려고 할 때 던져지는 에러입니다.

속성

.name: "EngineNotFoundError"
에러 이름입니다.
.scheme: string
연결할 프로토콜 이름입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

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.

해결책

engines 속성에서 연결할 엔드포인트의 프로토콜에 대해 엔진을 생성할 수 있는지 확인합니다.

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


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

ConnectionConflictError

상속원: SurrealError

클라이언트가 여러 엔드포인트에 동시에 연결하려고 할 때 던져지는 에러입니다.

속성

.name: "ConnectionConflictError"
에러 이름입니다.
.endpoint1: string
이미 연결된 엔드포인트입니다.
.endpoint2: string
다른 엔드포인트입니다. 
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.

.connect 메서드는 전달된 URL의 경로가 /rpc로 끝나지 않는 경우, 이를 끝에 추가합니다. 따라서 한 엔드포인트의 URL 경로가 /rpc로 끝나는 경우, 외관상으로는 에러가 발생하지 않을 수 있습니다.

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!

해결책

.connect 메서드를 호출하기 전에 .close 메서드를 호출하여 임의의 엔드포인트에 연결할 수 있습니다.

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

상속원: SurrealError

데이터베이스를 선택하기 전에 네임스페이스가 선택되지 않은 경우 던져지는 에러입니다. 또는 데이터베이스를 선택한 상태에서 네임스페이스를 선택하지 않은 상태로 만들려고 할 때도 던져집니다.

속성

.name: "MissingNamespaceError"
에러 이름입니다.
.database: string
데이터베이스 이름입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

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.

해결책

데이터베이스를 선택할 때는 네임스페이스도 함께 선택합니다.

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

상속원: SurrealError

RPC 응답이 에러를 나타내는 경우 던져지는 에러입니다. 연결된 프로토콜을 통한 통신이나 응답 본문의 디코딩에는 문제가 없지만, SurrealDB가 RPC 요청을 처리할 수 없음을 의미합니다.

속성

.name: "RpcResponseError"
에러 이름입니다.
.id?: string
RPC 요청을 식별하는 ID입니다. ID는 항상 <메서드 이름>_으로 시작합니다.
.code: number
SurrealDB 문서에 명시되어 있지는 않지만, 아마도 JSON-RPC의 에러 코드일 것입니다.

해결책

다양한 원인이 있을 수 있지만, 이 SDK가 지원하는 SurrealDB 버전과 RPC 요청을 처리하는 SurrealDB 버전이 다른 경우일 가능성이 있습니다.

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)

해결책

SurrelQL 구문이 올바른지 확인합니다.

Closed

상속원: SurrealError

연결이 강제로 종료되었음을 나타내는 에러입니다.

속성

.name: "Closed"
에러 이름입니다.

예를 들어 다음과 같은 경우에 이 에러를 얻습니다.

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 });

엔진

EngineError

상속원: SurrealError

엔진에 기인한 에러임을 나타냅니다. 이벤트 리스너를 통해 전달됩니다.

속성

.name: "EngineError"
에러 이름입니다.
.fatal: boolean | undefined
이 에러가 치명적인지 여부를 나타냅니다.

HttpEngineError

상속원: EngineError

HTTP 엔진에 기인한 에러임을 나타냅니다. 현재는 정의만 되어 있으며, 사용되지 않습니다.

속성

.name: "HttpEngineError"
에러 이름입니다.

WebSocketEngineError

상속원: EngineError

WebSocket 엔진에 기인한 에러임을 나타냅니다. RPC 요청을 식별하는 ID를 찾기 전에 응답 본문의 파싱에 실패했거나, WebSocket 객체에서 에러 이벤트를 받았을 때, WebSocket 연결을 끊었을 때 등에 사용됩니다.

이 SDK에서는 315x를 사용자 정의 상태 코드로 사용합니다. 이 범위는 IANA에서는 할당되지 않은 상태 코드입니다.

속성

.name: "WebSocketEngineError"
에러 이름입니다.
.code: number
다음 상태 코드 중 하나입니다.
  • 1000~1015: MDN Reference
  • 3150: WebSocket[^1] 인스턴스에서 “error” 이벤트를 받았음을 나타냅니다.
  • 3151: WebSocket 엔진이 등록한 “open” 이벤트 핸들러에서 에러가 발생했음을 나타냅니다. 연결 중 상태에서 연결 상태로 전환하는 과정에서 StateTransitionError가 발생했을 가능성이 높습니다.
  • 3152: WebSocket 엔진이 등록한 “message” 이벤트 핸들러에서 에러가 발생했음을 나타냅니다. 다양한 원인이 있을 수 있지만, 이벤트 핸들러에서 ServerResponseError 또는 RpcResponseError가 던져졌을 가능성이 높습니다. 잘못된 RPC 매개변수로 요청했을 가능성이 높으며, 이 경우 RPC 호출 메서드는 (기본적으로) 5초 후 타임아웃되어 실패합니다. SurrealDB v2.0.2 이전 버전에서는 더 광범위한 원인으로 타임아웃될 가능성이 있습니다.
  • 3153: ping 송수신에 실패했음을 나타냅니다. 일시적인 에러일 수도 있지만, 지속적으로 발생하는 경우 연결을 유지하지 못하고 있을 가능성이 있습니다.
  • 3154: WebSocket 엔진이 등록한 “close” 이벤트 핸들러에서 에러가 발생했음을 나타냅니다. 연결 해제 중 상태에서 연결 해제 상태로 전환하는 과정에서 StateTransitionError가 발생했을 가능성이 높습니다.
다음 상태 코드는 제외합니다. 이 SDK에서는 에러로 처리하지 않습니다.
  • 1000: 정상적으로 연결이 해제되었습니다.
  • 1001: 조기 연결 해제는 흔히 발생합니다.
  • 1004: 예약됨.
  • 1005: 예약됨.
  • 1006: 예약됨.
  • 1015: 예약됨.

^1: WebSocket은 런타임이 전역 변수에 정의하는 클래스이거나, ws의 클래스일 수 있습니다.

해결책

1002,1003,1007…1011,1014,3150,3151,3154
이 상태 코드에서 자동으로 복구하는 방법은 거의 없습니다. 런타임이나 SurrealDB 설정, 하드 코딩된 구현을 수정해야 합니다.
3152
메서드에 전달한 인수(즉, RPC 요청 내용)가 올바른지 확인합니다.
1012,1013,3153
실험적인 기능인 autoReconnect()를 사용하여 자동으로 복구할 수 있을 것입니다.

StateTransitionError

상속원: SurrealAggregateError

상태 전환 중에 이벤트 리스너의 실행에 실패한 경우 던져지는 에러입니다.

속성

.name: "StateTransitionError"
에러 이름입니다.
.from: string
상태 전환 시작 시 상태입니다.
.to: string
전환할 상태입니다.
.fallback: string
상태 전환에 실패한 경우 대체 전환 대상입니다. .to와 동일한 값이면 강제로 전환되었음을 의미합니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

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

상속원: SurrealError

연결되지 않은 상태에서 RPC 요청을 보내려고 할 때 던져지는 에러입니다.

속성

.name: "ConnectionUnavailableError"
에러 이름입니다.

ServerResponseError

상속원: SurrealError

응답을 PRC 응답으로 파싱할 수 없는 경우 던져지는 에러입니다. RpcResponseError와는 다릅니다.

속성

.name: "ServerResponseError"
에러 이름입니다.

해결책

일반적으로 이 에러가 던져지는 경우는 없어야 하지만, 만약 던져진다면 이 SDK가 지원하는 SurrealDB 버전과 RPC 요청을 처리하는 SurrealDB 버전이 다른 경우일 가능성이 있습니다.

CBOR

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"
에러 이름입니다.

해결책

디코딩 대상 바이트 배열이 올바른 CBOR 형식인지 확인합니다.

CborTooLittleDataError

상속원: CborWellFormednessError

입력 바이트가 불완전함을 나타냅니다.

RFC8949

속성

.name: "CborTooLittleDataError"
에러 이름입니다.

해결책

디코딩 대상 바이트 배열이 올바른 CBOR 형식인지 확인합니다.

CborSyntaxError

상속원: CborWellFormednessError

입력 바이트가 CBOR 인코딩 형식과 일치하지 않음을 나타냅니다.

RFC8949

속성

.name: "CborSyntaxError"
에러 이름입니다.

해결책

디코딩 대상 바이트 배열이 올바른 CBOR 형식인지 확인합니다.

CborMaxDepthReachedError

상속원: CborError

CBOR 인코딩 또는 디코딩 시 JavaScript 객체의 깊이가 최대값에 도달한 경우 던져지는 에러입니다. 객체 또는 배열에 들어갈 때마다 깊이가 1씩 증가합니다.

속성

.name: "CborMaxDepthReachedError"
에러 이름입니다.
.maxDepth: number
최대 깊이입니다.

해결책

옵션의 .maxDepth 상한을 완화하거나, 객체의 중첩이 얕아지도록 데이터 구조를 재검토합니다.

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


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

CborUnsafeMapKeyError

상속원: CborError

CBOR 인코딩 또는 디코딩 시 안전하지 않은 맵 키가 발견된 경우 던져지는 에러입니다.

속성

.name: "CborUnsafeMapKeyError"
에러 이름입니다.
.key: unknown
안전하지 않다고 판단된 맵 키입니다.

JSON

JsonError

상속원: SurrealError

@tai-kun/surrealdb/json이 명시적으로 던지는 JSON-formatter입니다.

속성

.name: "JsonError"
에러 이름입니다.

JsonUnsafeMapKeyError

상속원: JsonError

JSON 디코딩 시 안전하지 않은 맵 키가 발견된 경우 던져지는 에러입니다.

속성

.name: "JsonUnsafeMapKeyError"
에러 이름입니다.
.key: unknown
안전하지 않다고 판단된 맵 키입니다.