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§
- Error
Info - 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. - Parse
Error - A parser error with source position information.
Enums§
- Engine
Error - The typed engine error channel. Per ADR 0003 it has four variants:
- Error
Kind - The specific, TCK-aligned name of an engine error.
kind()returns the most specific name available; nested detail (e.g. theUnsupportedIndexOrConstraintin"SyntaxError: UnsupportedIndexOrConstraint: …") stays in the message. - Error
Stage - 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).
- Nested
Error Class - The openCypher error class nested in a still-stringly
Syntax/Semantic/Executionpayload: the legacy constraint-class tokens first, then a leading<Class>:name token.nested_error_classreturnsNonewhen the payload carries no recognized class — the caller’s variant-level class is then the answer. - Storage
Error - Errors that can occur in the storage layer.
- TckError
Class - One of the eight openCypher TCK error classes. The spec harness
(ADR-0482) asserts an expected class, while
ErrorKindcarries the finer-grained detail. EveryErrorKindmaps to exactly one class viaErrorKind::tck_class.
Constants§
- ARGUMENT_
ERROR_ CODE - The
codeof a DDL argument-value rejection (ArgumentError): the code Neo4j 2026.09 sends for an invalidOPTIONS/indexConfigvalue (ADR-0489). - ARGUMENT_
VALUE_ ERROR_ CODE - The
codeof a run-time argument rejection (ArgumentValue): what Neo4j 2026.10.1 sends forrange()’s zero step and for thesubstring()/left()/right()int32-range rejections — the sameArgumentErrorclass asARGUMENT_ERROR_CODE, a different stage. - ARITHMETIC_
ERROR_ CODE - The
codeof an arithmetic failure (Arithmetic: division or modulo by zero, rounding necessary). - CONSTRAINT_
VALIDATION_ FAILED_ CODE - The
codeof 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 afterErrorKind::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
codeof an unknown database, from adbextra or aUSEtarget. - 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
SyntaxErrorclass). - INTERNAL_
ERROR_ INFO - The internal class’s own row of the ADR-0307 table: the genericized
UnknownErrorcode, the internal GQLSTATUS, the internal stage, never retryable (ADR-0260 — an internal failure is not the statement’s fault).error_inforeturns 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
codeof a retryable processing cap (concurrent-logical-workspace-limit). Transient, so a driver’s managed transaction retries the statement. - OUTDATED_
CODE - The
codeof a write-write conflict: aTransientError, so drivers’ managed transactions retry it (the engine never does, ADR-0017). - PARAMETER_
MISSING_ CODE - The
codeof a statement that references an absent parameter (ADR-0308). - PROCEDURE_
NOT_ FOUND_ CODE - The
codesent when a query calls a procedure the engine does not register (ADR-0138): neo4j-browser branches on the exact Neo4j code for itsdbms.clientConfig→dbms.listConfigfallback. - SEMANTIC_
ERROR_ CODE - The
codeof every other caller-facingSemanticandExecutionengine error. - SYNTAX_
ERROR_ CODE - The
codeof a statement the parser rejects (engineSyntax). - TRANSACTION_
OUT_ OF_ MEMORY_ CODE - The
codeof 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-retryableClientErrorclass (ADR-0307 item 4). - TRANSACTION_
TIMED_ OUT_ CODE - The
codeof a query stopped by--query-timeout-secs(the engine’sCancelled). - TYPE_
ERROR_ CODE - The
codeof a type failure (Type,TypeError,InvalidArgumentType). - UNKNOWN_
ERROR_ CODE - The
codesent 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 fixedINTERNAL_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 hase) — 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_classused 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_messagegenericizes 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.boundarynames 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 onesNestedErrorClasscloses 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 typedrelate_error::EngineErrorand the executor’s string-carryingcrate::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.