Reference
Helix query failures expose a stable machine-readable code separately from the
human-readable diagnostic. Branch on the code; log or display the message.
Messages can gain context over time and are not a compatibility contract.
This page covers errors raised by the HelixDB engine in every run mode. A Helix Cloud
gateway can also return its own codes, such as rate_limited and unauthorized; see
Helix Cloud gateway errors.
TypeScript release compatibility
@helix-db/helix-db 3.1.0 exposes HelixError.code, statusCode,
serverMessage, rawBody, and explicit retryable metadata. The published
3.0.4 package lacks these structured fields. Docker v0.0.5 already
returns a confirmed transaction conflict as HTTP 409 with
{"error":"transaction_conflict","msg":"<diagnostic>"}.
Use both error.code === "transaction_conflict" and error.statusCode === 409
to recognize that condition. Reload the asset before rebuilding the mutation;
do not match diagnostic wording. A dropped connection after sending a write is
a Network failure with an unknown commit outcome, not proof that the write
was aborted. An explicit writer_fenced_commit_outcome_unknown response is also
distinct from a conflict and carries retryable: false. Reconcile state before
resubmitting such writes. The SDK does not automatically replay mutations.
This compatibility statement concerns transaction conflicts; it does not claim
that v0.0.5 implements every newer error classification in the reference below.
HTTP error envelope
Every non-success response fromPOST /v2/query uses error for the static
code and msg for the readable message:
retryable when the code’s
class settles it. The response never adds a separate code
field. A non-JSON response from an older proxy or intermediary is still exposed
by each SDK as readable details with no code. An unknown path or method returns
an empty 404 or 405.
Failure classes
Every code belongs to exactly one class, and the class alone sets the HTTP status, the gRPC status, theretryable field and whether a failed write is
proven to have committed nothing. The reference lists
each code’s status.
retryable appears only in this native envelope. A Cypher or SQL error body with
details, and every gRPC status, omits it; use the class instead.
HTTP 409 has two classes, so branch on retryable rather than the status. A
retryable conflict (transaction_conflict, request_read_view_changed or
stale_index_generation, with retryable: true) can succeed when resent
unchanged. A conflict with the database’s state, such as
unique_constraint_violation (retryable: false), fails again until that
state changes: choose another value or reconcile first.
HTTP 429 has several causes, and only some are transient. Turn off generic HTTP
client retries on 429 and branch on error:
An index-management request with several create, drop, retry or abort
operations commits each operation as it runs. If a later operation fails, the
earlier ones stay committed, so read the index state before resending such a
batch.
Cypher errors
POST /v2/cypher, POST /v2/cypher/explain, POST /v2/sql and POST /v2/sql/explain report a failed
statement with the same error and msg fields and a details object:
error is the category and details.detail the specific condition. Both are lower
snake case, like every code on this page. details.phase is compile (nothing ran)
or runtime, and span locates the failing statement text when it is known. A
failed statement commits nothing. gRPC carries the same JSON in the status details.
Embedded SDK errors join the three parts into one code,
category:phase:detail, such as syntax_error:compile:undefined_variable.
Request, storage, and transaction failures on the Cypher routes keep the native
envelope, its retryable field, and the codes below.
The Cypher guide lists
the
details.detail code for each construct outside the supported profile. SQL
that the translation rejects reports unsupported_feature with sql_construct
(msg names the construct), and an unqualified column in a statement with several
tables reports syntax_error with ambiguous_column; the
SQL guide lists the rest.
Access the code in an SDK
QueryErrorCode. SDK wire fields remain
open strings so a newer server’s unknown future code is preserved rather than
being collapsed or rejected.
Other query boundaries
For gRPC, the status message remains human-readable and the same static code is attached as ASCII metadata underhelix-error-code. The gRPC status is the
code’s class status, so unique_constraint_violation is
FAILED_PRECONDITION and index_backpressure is RESOURCE_EXHAUSTED.
Embedded Rust errors expose error_code(). UniFFI errors carry two explicit
fields named error and msg; generated Python, Node, and Go bindings pass
that pair into their SDK error objects. Embedded callers never need to infer a
code from exception text.
Stability and retry rules
- Existing code strings are frozen compatibility identifiers. New codes may be added, so applications must preserve and safely handle unknown values.
- A code describes the failure, not whether replaying a particular mutation is safe. Retry only idempotent work or work protected by an application-level idempotency key.
- HTTP 409 with
retryable: true(transaction_conflict,request_read_view_changed,stale_index_generation) is normally retryable with bounded backoff. A 409 withretryable: falseconflicts with the database’s state and fails again when resent; branch onretryableor the code, not the status alone. index_backpressure(HTTP 429) rejects the whole request before it takes effect and carriesretryable: true. Retry it unchanged with bounded backoff; see index backpressure. Other 429 codes are not all transient; see the 429 table.- A 408 on a write does not mean it failed. A write that awaits durability
waits at most 30 seconds for its WAL upload, then returns
query_deadline_exceededalthough it is applied and may still become durable. Read the state back before resending. - Availability and lifecycle failures should be retried only after the named condition changes. Validation and planning failures require a corrected request or schema/index configuration.
internal_*,storage_error, andresponse_serialization_errorare opaque by design. Retain themsgand server logs when escalating them.
Error-code reference
“Correctable” means whether a caller can change its request or deployment state to address the failure. Each code has one HTTP status at every boundary, exceptinternal_planner_error: 400 here, and 500 as a
Cypher category on the Cypher and SQL routes.
Request validation
Planning
Execution
Active-text mutation limits
active_text_mutation_limit_exceeded reports a deterministic rejection before the
write transaction commits: one indexed text document is too large. The request’s graph
changes are not committed. The error is caller-correctable and uses HTTP 400, gRPC
InvalidArgument, or the embedded InvalidRequest binding category. It is not a
transient rate limit or an unknown write outcome; retrying the identical mutation does
not resolve the limit.
For example, the HTTP query service returns:
error, not the wording in msg. The diagnostic identifies the resource,
the document’s usage and its allowance. See active-text admission limits
for the default allowances. The same engine policy applies to standalone databases;
embedded configurations may override it.
Index lifecycle
Retryable conflicts
Availability and migration
Internal failures
Migrate direct HTTP consumers
The field names changed while their roles stayed the same:
Old response:
code to error and their diagnostic read from error
to msg.