Errors

Each error relate reports has a stable id, and each id is an anchor on this page: https://relatedb.ai/docs/reference/errors/#<id>. A row gives the message pattern as relate prints it, where it is recorded, the cause, the remedy, whether retrying the same statement can succeed, and the CLI exit code. The tables are generated from one data file, so this page and its markdown twin list the same entries.

Synopsis

On the CLI, a failed statement prints its message on stderr and exits with the exit codeexit code The number a relate run returns to the shell; each nonzero value names a class of failure, such as 2 for usage, 5 for conflict, 6 for a rejected statement. Read more in the glossary of its class. In --mode envelope, --json and --jsonl, it also prints an error objecterror object The JSON object a failed query run prints on stdout in the json, jsonl, envelope and speedscope modes: the class, the kind, the message, the exit code. Read more in the glossary on stdout. The object's code is the class, kind is the engine's error variant, retryable is true for a write-write conflict and for a --concurrent-logical-workspace-limit refusal while other statements hold the workspace pool, and message repeats the stderr text.

relate --mode envelope 'RETURN $x AS x'

The first line of the output is stderr, the second is stdout:

semantic error: ParameterMissing: Expected parameter(s): x
{"error":{"code":"validation_error","exit_code":6,"kind":"semantic","message":"semantic error: ParameterMissing: Expected parameter(s): x","retryable":false}}

A syntax error adds column and source, so a caller can point at the failing token without parsing the message:

syntax error: parse error: expected RightParen, got "RETURN" (RETURN)
  MATCH (n RETURN n
           ^
{"error":{"code":"validation_error","column":10,"exit_code":6,"kind":"syntax","message":"syntax error: parse error: expected RightParen, got \"RETURN\" (RETURN)   MATCH (n RETURN n            ^","retryable":false,"source":"MATCH (n RETURN n"}}

relate agent-context prints the exit codes of the installed version:

Exit codes:
  0  success: success, including an empty result
  1  fatal_error: runtime failure: store open or I/O error, capacity limit, query execution failure, internal error
  2  usage_error: unknown flag, bad or missing value, extra positional
  5  conflict: write-write conflict, or the store is locked by another opener
  6  validation_error: the statement is rejected: syntax, semantic or type error
  7  timeout: a statement exceeded --timeout

In the tables, a message's <name> marks a variable part and … is an elision in the source. A dash (—) means the sources do not state the value, or it does not apply to that surfacesurface Any front door to the relate engine: the CLI, a language client, the C ABI, the WebAssembly build, or a server that relate serve hosts. Read more in the glossary.

CLI errors

Errors and notices from the relate command itself: statement classes, flag and environment checks, and the skill installer.

Engine errors

Errors the engine raises on every surface. The CLI prints them inside the class prefix of its row (semantic error:, syntax error:, type error:).

HTTP Query API errors

Errors from relate serve --http, in the Query API v2 error envelope.

Bolt errors

Errors from relate serve --bolt that the Bolt surface adds to the engine errors.

MCP errors

Errors from relate serve --mcp. A tool refusal comes back as a tool result with isError: true; a protocol error is a JSON-RPC error with the code in its row.

Client library errors

Refusals a client library raises itself, before or around the engine: the Node.js client's argument checks, the WebAssembly build's storage and loading errors, and the C ABI's own messages. The Error column names the surface and, where the client has one, the class.

GQL status index

Each GQL status code, at its own anchor (#gql-42n00), with the entries that report it.

Python exception classes

The classes the Python client (relate-db) raises, at their own anchors.

Notifications

Notifications are not errors: a statement that raises one still runs. EXPLAIN and PROFILE print them after the plan, and --mode envelope carries them in notifications.

See also

• Connect your agent to relate: reading an error object and branching on its exit code
• Exit codes and errors: the exit code table and every field of the error object
• Troubleshooting: from an error message or exit code to the guide that fixes it