Skip to main content

Crate relate_error

Crate relate_error 

Source
Expand description

Typed engine errors for Relate.

This crate hosts EngineError, the typed error channel that replaces the engine’s historical Result<_, String>, and — since ADR-0502 §2 — the engine’s one classification of a query-engine error, error_info: the Neo4j status code, the GQLSTATUS, the compile/runtime/internal stage (ADR-0319) and the drivers’ transient test, single-sourced here so every surface (Bolt, HTTP, the CLI classifier, Python, the C ABI) is a thin derivation, never a second table. It depends on relate-parser (for ParseError) and relate-core (for the query-engine Error that error_info classifies, and for the shared error-kind vocabulary, which ADR-0502 moved down to core and this crate re-exports). See docs/adr/0003-tck-named-error-kinds.md and docs/adr/0502-typed-c-abi-v2.md.

§The prime invariant

Display output is preserved verbatim against the pre-refactor stringly errors: a parse-time failure renders exactly as ParseError’s "parse error: …", a storage failure exactly as StorageError’s message, and a semantic/runtime failure exactly as the historical "Kind: message" shape. Changing an error message is not a breaking change; changing a kind is (per ADR 0003).

Structs§

ErrorInfo
The classification of one query-engine error (ADR-0502 §2): everything the ABI v2 error shape carries beside the message, and everything the surfaces need to render a failure. Built only by error_info — the one exhaustive classification, so a new engine variant does not compile until it is classified here.
ParseError
A parser error with source position information.

Enums§

EngineError
The typed engine error channel. Per ADR 0003 it has four variants:
ErrorKind
The specific, TCK-aligned name of an engine error. kind() returns the most specific name available; nested detail (e.g. the UnsupportedIndexOrConstraint in "SyntaxError: UnsupportedIndexOrConstraint: …") stays in the message.
ErrorStage
Which stage of statement handling an error belongs to (ADR-0319): a compile-class error fails the statement before any work is done (Bolt’s RUN), a runtime-class error is discovered while producing rows (Bolt’s first PULL/DISCARD), and an internal-class error is not the statement’s fault and is genericized at every trust boundary (ADR-0260).
NestedErrorClass
The openCypher error class nested in a still-stringly Syntax/ Semantic/Execution payload: the legacy constraint-class tokens first, then a leading <Class>: name token. nested_error_class returns None when the payload carries no recognized class — the caller’s variant-level class is then the answer.
StorageError
Errors that can occur in the storage layer.
TckErrorClass
One of the eight openCypher TCK error classes. The spec harness (ADR-0482) asserts an expected class, while ErrorKind carries the finer-grained detail. Every ErrorKind maps to exactly one class via ErrorKind::tck_class.

Constants§

ARGUMENT_ERROR_CODE
The code of a DDL argument-value rejection (ArgumentError): the code Neo4j 2026.09 sends for an invalid OPTIONS/indexConfig value (ADR-0489).
ARGUMENT_VALUE_ERROR_CODE
The code of a run-time argument rejection (ArgumentValue): what Neo4j 2026.10.1 sends for range()’s zero step and for the substring()/left()/right() int32-range rejections — the same ArgumentError class as ARGUMENT_ERROR_CODE, a different stage.
ARITHMETIC_ERROR_CODE
The code of an arithmetic failure (Arithmetic: division or modulo by zero, rounding necessary).
CONSTRAINT_VALIDATION_FAILED_CODE
The code of a uniqueness-constraint violation.
COUNT_UNION_MIX_MESSAGE
The two COUNT { … } statement-shape UNION rule message bodies (CIP-66), single-sourced because two layers raise them byte-identically after ErrorKind::DifferentColumnsInUnion’s name: the front’s validate battery (validate_count_subquery_union_shapes, rejecting before lowering) and the executor’s per-row defense-in-depth scan (eval_count_query, for callers that bypass validation). The rendered text is pinned contract (ADR-0003’s message immutability rule).
COUNT_UNION_OMITTED_MESSAGE
DATABASE_NOT_FOUND_CODE
The code of an unknown database, from a db extra or a USE target.
GQLSTATUS_DATABASE_NOT_FOUND
The GQLSTATUS of an unknown database (ADR-0116 §9).
GQLSTATUS_GENERAL
The GQL general error code: the code of a caller-facing class without a class-specific GQLSTATUS.
GQLSTATUS_SYNTAX
The GQLSTATUS of a rejected statement (the SyntaxError class).
INTERNAL_ERROR_INFO
The internal class’s own row of the ADR-0307 table: the genericized UnknownError code, the internal GQLSTATUS, the internal stage, never retryable (ADR-0260 — an internal failure is not the statement’s fault). error_info returns exactly this row for an engine-internal failure, and publishes it for the boundaries that fail before the engine sees anything — a null or poisoned handle, an argument decode refusal, a caught panic — so they render the internal classification without fabricating an engine error to classify.
INTERNAL_MESSAGE
The fixed client message every trust boundary substitutes for an internal-class failure (ADR-0260, OPLANE_REQ-00340359): engine-internal, IO, storage and locked errors — and caught panic payloads — can carry file paths and engine internals, so their Display text stays server-side (logged by the boundary) and the client sees this. The caller-facing classes pass their Display text through verbatim.
MEMORY_POOL_OUT_OF_MEMORY_CODE
The code of a retryable processing cap (concurrent-logical-workspace-limit). Transient, so a driver’s managed transaction retries the statement.
OUTDATED_CODE
The code of a write-write conflict: a TransientError, so drivers’ managed transactions retry it (the engine never does, ADR-0017).
PARAMETER_MISSING_CODE
The code of a statement that references an absent parameter (ADR-0308).
PROCEDURE_NOT_FOUND_CODE
The code sent when a query calls a procedure the engine does not register (ADR-0138): neo4j-browser branches on the exact Neo4j code for its dbms.clientConfig → dbms.listConfig fallback.
SEMANTIC_ERROR_CODE
The code of every other caller-facing Semantic and Execution engine error.
SYNTAX_ERROR_CODE
The code of a statement the parser rejects (engine Syntax).
TRANSACTION_OUT_OF_MEMORY_CODE
The code of both memory conditions — a write over --logical-graph-size-limit (Capacity) and a result over --max-result-bytes — the one Neo4j memory code in the non-retryable ClientError class (ADR-0307 item 4).
TRANSACTION_TIMED_OUT_CODE
The code of a query stopped by --query-timeout-secs (the engine’s Cancelled).
TYPE_ERROR_CODE
The code of a type failure (Type, TypeError, InvalidArgumentType).
UNKNOWN_ERROR_CODE
The code sent when an internal-class engine error is genericized at a trust boundary (ADR-0260, ADR-0307).

Functions§

client_message
The message a trust boundary may show the client for e — the message-exposure half of ADR-0260 (OPLANE_REQ-00340359), derived from the one classification beside it: the caller-facing classes carry the engine’s Display text; the internal class carries the fixed INTERNAL_MESSAGE, because engine-internal, IO, storage and locked messages can hold file paths and engine internals. A boundary that wants the original for its own log reads it itself (it has e) — this helper never leaks it.
duplicate_variable_detail
The one spelling of a duplicate-binding rejection’s detail (after the VariableAlreadyBound: kind token): variable '<name>' already declared.
error_info
Classify a query-engine error (ADR-0307, single-sourced by ADR-0502 §2). Exhaustive on purpose: a new engine variant does not compile until it has a code, a GQLSTATUS, a stage and a retryable verdict — the match that Bolt’s failures::error_class used to own alone.
log_internal_original
Log the internal class’s original message to stderr — the boundary-log half of the same ADR-0260 policy (OPLANE_REQ-00340359): the class whose message client_message genericizes is the one whose original an operator needs server-side, so the stage decision and the log format live here once, beside the redaction they complement. boundary names the calling surface in the line ("bolt", "http", "ffi"); a boundary that gates its channel (the C ABI’s host opt-in) applies its gate at its own call site.
nested_error_class
The one canonical scan (AGENTS.md: one canonical helper per policy) of a still-stringly payload’s nested class, consulted by both consumers of the nested-class fact: error_info’s GQLSTATUS for these payloads, and the language bindings’ binding_error_metadata. A string that merely resembles a typed class’s token does not adopt that class — the recognized names are the ones NestedErrorClass closes over.
undefined_variable_detail
The one spelling of an undefined-variable rejection’s detail (after the UndefinedVariable: kind token): variable '<name>' not defined. Both error channels — the typed relate_error::EngineError and the executor’s string-carrying crate::Error — render the same text.
unknown_function_detail
The one spelling of an unknown-function rejection’s detail (after the UnknownFunction: kind token): unknown function <name>(). The planner’s binder, the executor’s scalar-eval backstop and the front’s preview-name admission gate all render this text, so a gated name is rejected exactly like a name the registry has never known.