Error codes

Every QQL error carries a stable code, a broad kind, a human-readable message, and an optional zero-based UTF-8 byte span [start, end). The message text is not normative — match on the code, which is fixed by the conformance fixtures. A code already asserted by a v1 invalid fixture cannot change before QQL 2; new codes may only refine previously unspecified cases.

The tables below cover the full set of codes the reference implementation emits. Codes are grouped by the failure family:

Prefix	Family
`QQL-LEX-*`	Lexical failures
`QQL-PARSE-*`	Syntax, clause order, and value-range failures
`QQL-VALIDATION-*`	Semantic validation of a parsed program
`QQL-PLAN-`, `QQL-MISSING-`, `QQL-UNKNOWN-*`, `QQL-VECTOR-KIND`	Planning and schema resolution
`QQL-JSON-*`	Value conversion to JSON
`QQL-EMBEDDING-*`	UPSERT embedding inference
`QQL-EDGE-*`	In-process edge backend capability and runtime failures

Error shape per host

The same structured fields are projected differently by each host binding.

Host	Shape
Rust	`QqlError { kind, code, message, span: Option<Span { start, end }>, fields, source }`; the `kind` is one of `Lex`, `Parse`, `Validation`, `Execution`, `Transport`, `Backend`
Python	Error attributes `code`, `kind`, and `span`
Node.js	`error.code`, `error.kind`, `error.span` on the thrown error
WebAssembly	`AnalysisError { code, message, start, end }` (nulls when a span is absent)

Lexical

Code	Meaning
`QQL-LEX-CHAR`	A character cannot start any token
`QQL-LEX-STRING`	Unterminated string literal

Parse

Code	Meaning
`QQL-PARSE-STATEMENT`	Unknown or legacy statement keyword (`SELECT`, `INSERT`, `BOOST`)
`QQL-PARSE-EMPTY-STATEMENT`	Empty script element, such as a leading or repeated separator
`QQL-PARSE-EXPECTED`	A required token is missing (for example an unmatched parenthesis)
`QQL-PARSE-QUERY-INPUT`	Invalid query input form (a bare number is not a query input)
`QQL-PARSE-CLAUSE-ORDER`	Duplicate or out-of-order query clause
`QQL-PARSE-VECTOR-KIND`	`AS` is not `DENSE`, `SPARSE`, `MULTI`, or `MULTIVECTOR`
`QQL-PARSE-DUPLICATE-CTE`	Duplicate CTE name in one script
`QQL-PARSE-DUPLICATE-KEY`	Duplicate object or config key (ASCII case-insensitive)
`QQL-PARSE-POSITIVE-INTEGER`	Value must be a positive integer (for example `LIMIT`, `CANDIDATES`, vector size)
`QQL-PARSE-NONNEGATIVE-INTEGER`	Value must be non-negative (for example `OFFSET`, `VALUES_COUNT`)
`QQL-PARSE-SYNTAX`	Production-specific syntax or range failure
`QQL-PARSE-COMPARISON`	Expected a comparison operator
`QQL-PARSE-CONTEXT`	`CONTEXT` requires at least one positive/negative pair
`QQL-PARSE-CROSS-RERANK`	`CROSS RERANK` requires `TEXT '…'` or a string query input
`QQL-PARSE-EMBED`	`EMBED USING` requires `DENSE`, `SPARSE`, `MULTI`, `IMAGE`, or `MODEL`
`QQL-PARSE-EMBEDDING`	Duplicate clause in a HYBRID embedding spec
`QQL-PARSE-ESCAPE`	Unterminated escape sequence
`QQL-PARSE-FIELD`	Expected a field name
`QQL-PARSE-FILTER`	Expected a filter operator (for example `IS` requires `NULL`/`EMPTY`)
`QQL-PARSE-FLOAT`	Invalid float literal
`QQL-PARSE-IDENTIFIER`	Expected an identifier or quoted name
`QQL-PARSE-IN`	`IN` / `NOT IN` requires a non-empty value list
`QQL-PARSE-INDEX-TYPE`	Unsupported `CREATE INDEX` field type
`QQL-PARSE-INTEGER`	Invalid integer literal
`QQL-PARSE-LITERAL`	Expected a scalar literal
`QQL-PARSE-MATCH-ANY`	`MATCH ANY` requires a non-empty exact-value list
`QQL-PARSE-NUMBER`	Expected a number
`QQL-PARSE-OBJECT-KEY`	Expected an object key
`QQL-PARSE-PAYLOAD-SELECTOR`	`WITH PAYLOAD` requires `true`, `false`, `INCLUDE (...)`, or `EXCLUDE (...)`
`QQL-PARSE-POINT-ID`	A point ID must be an unsigned integer or a string
`QQL-PARSE-POINT-IDS`	A point ID list cannot be empty
`QQL-PARSE-PREFETCH`	`PREFETCH` cannot be empty
`QQL-PARSE-SAMPLE`	`SAMPLE` requires `RANDOM`
`QQL-PARSE-SELECTOR`	A selector list cannot be empty
`QQL-PARSE-SEPARATOR`	Multiple statements must be separated by a semicolon
`QQL-PARSE-STATEMENT-LIMIT`	A script may contain at most 256 statements
`QQL-PARSE-TRAILING`	Unexpected trailing token
`QQL-PARSE-UPDATE`	Expected `VECTOR` or `PAYLOAD` after `SET`
`QQL-PARSE-VALUE`	Unexpected value token

Validation

Code	Meaning
`QQL-VALIDATION-FROM`	A top-level query lacks `FROM`
`QQL-VALIDATION-PREFETCH-CTE`	A `PREFETCH` name does not resolve to a CTE
`QQL-VALIDATION-FUSION-PREFETCH`	`QUERY FUSION` has no `PREFETCH`
`QQL-VALIDATION-RERANK-PREFETCH`	`QUERY RERANK` has no `PREFETCH`
`QQL-VALIDATION-POINTS-CLAUSE`	`QUERY POINTS` uses a clause it cannot accept
`QQL-VALIDATION-UPSERT-ID`	An UPSERT point lacks a valid `id` key
`QQL-VALIDATION-MMR`	MMR `DIVERSITY` is outside `[0, 1]` or not finite
`QQL-VALIDATION-HYBRID`	Invalid `USING HYBRID` / `QUERY HYBRID` combination
`QQL-VALIDATION-FILTER-INJECT`	`inject_filter` does not apply to this statement type
`QQL-VALIDATION-ID-PREDICATE`	A point ID predicate uses an operator other than `=`, `!=`, `IN`, or `NOT IN`
`QQL-VALIDATION-POINT-ID`	A value used as a point ID is neither an unsigned integer nor a string
`QQL-VALIDATION-ACORN-SELECTIVITY`	`max_selectivity` requires `PARAMS (acorn = true, …)`
`QQL-VALIDATION-CONFIG`	Invalid collection configuration block
`QQL-VALIDATION-CONSISTENCY`	`consistency` must be a non-negative integer factor or `majority` / `quorum` / `all`
`QQL-VALIDATION-CREATE-MODEL`	`CREATE COLLECTION … HYBRID` rejects a single dense `MODEL`
`QQL-VALIDATION-CROSS-RERANK-PREFETCH`	`CROSS RERANK` requires `PREFETCH`
`QQL-VALIDATION-FEEDBACK-STRATEGY`	A feedback strategy parameter is not numeric
`QQL-VALIDATION-FUSION`	The fusion method must be `RRF` or `DBSF`
`QQL-VALIDATION-GEO`	Invalid geo coordinates, radius, or polygon ring
`QQL-VALIDATION-LIMIT-OVERFLOW`	`LIMIT` + `OFFSET` (or hybrid candidate scaling) overflows `u64`
`QQL-VALIDATION-PREFETCH`	This query expression does not accept `PREFETCH`
`QQL-VALIDATION-RECOMMEND-STRATEGY`	Unknown `RECOMMEND STRATEGY`
`QQL-VALIDATION-RERANK-USING`	`RERANK` requires `USING <vector>`
`QQL-VALIDATION-SCORE`	A score threshold must be finite
`QQL-VALIDATION-SEARCH-PARAM`	Unknown search parameter
`QQL-VALIDATION-USING`	This query expression does not accept `USING`
`QQL-VALIDATION-VECTOR`	Invalid vector value

Planning

Code	Meaning
`QQL-PLAN-VECTOR-KIND`	Structural vector input and the declared `AS` role disagree
`QQL-MISSING-USING`	Schema inference is ambiguous; add `USING <vector>`
`QQL-UNKNOWN-VECTOR`	The explicit vector name does not exist in the collection
`QQL-VECTOR-KIND`	The schema role conflicts with the requested role, or the kind is unresolved before embedding
`QQL-PLAN-COLLECTION`	A query collection name must not be empty
`QQL-PLAN-CROSS-RERANK-CANDIDATE`	A `CROSS RERANK` prefetch must plan as a search query
`QQL-PLAN-CROSS-RERANK-CTE`	`PREFETCH` references an unknown CTE
`QQL-PLAN-CROSS-RERANK-MODEL`	`CROSS RERANK MODEL` must not be empty
`QQL-PLAN-CROSS-RERANK-PREFETCH`	`CROSS RERANK` requires at least one `PREFETCH`
`QQL-PLAN-CROSS-RERANK-QUERY`	`CROSS RERANK` query text must not be empty
`QQL-PLAN-FUSION-PREFETCH`	`FUSION` requires at least one prefetch
`QQL-PLAN-PREFETCH-CTE`	`PREFETCH` references an unknown CTE
`QQL-PLAN-PREFETCH-GROUP`	`GROUP BY` is not supported inside a `PREFETCH` source
`QQL-PLAN-RERANK-PREFETCH`	`RERANK` requires at least one `PREFETCH`
`QQL-PLAN-RERANK-USING`	`RERANK` requires a non-empty `USING` vector name
`QQL-PLAN-RRF-PARAMS`	`rrf_k` and `rrf_weights` are valid only with `RRF` fusion
`QQL-PLAN-RRF-WEIGHTS`	`rrf_weights` length must equal the prefetch count
`QQL-PLAN-UNSUPPORTED-PREFETCH`	`POINTS` / `CROSS RERANK` are not supported inside `PREFETCH`
`QQL-REST-CLIENT-SIDE`	The operation is executed client-side and has no single Qdrant REST route
`QQL-BACKEND`	Generic backend or transport failure

Value conversion

Code	Meaning
`QQL-JSON-NONFINITE`	A non-finite float cannot be serialized to JSON
`QQL-JSON-NUMBER`	A value cannot be represented as a JSON number

Embedding

Code	Meaning
`QQL-EMBEDDING-TOPOLOGY`	UPSERT embedding inference is ambiguous across the collection topology
`QQL-EMBEDDING-TARGET`	The UPSERT embedding target is absent or has the wrong role

Edge backend

The in-process edge backend reports capability limits with a stable QQL-EDGE-UNSUPPORTED-* code instead of a generic failure. These errors usually carry a remediation hint pointing at remote Qdrant.

Code	Meaning
`QQL-EDGE-UNSUPPORTED-GROUP-BY`	`GROUP BY` / query groups are not available offline
`QQL-EDGE-UNSUPPORTED-SHARD`	`SHARD` routing or collection sharding options are not available offline
`QQL-EDGE-UNSUPPORTED-SHARD-KEY`	`CREATE` / `DROP SHARD KEY` are not available offline
`QQL-EDGE-UNSUPPORTED-ALTER`	`ALTER COLLECTION` is not available offline
`QQL-EDGE-UNSUPPORTED-COLLECTION-PARAMS`	Collection `WITH PARAMS` is not available offline
`QQL-EDGE-UNSUPPORTED-ACORN`	`PARAMS (acorn = ...)` is not available offline
`QQL-EDGE-UNSUPPORTED-TIMEOUT`	`PARAMS (timeout = ...)` is not available offline
`QQL-EDGE-UNSUPPORTED-CONSISTENCY`	`PARAMS (consistency = ...)` is not available offline
`QQL-EDGE-UNSUPPORTED-RECOMMEND-STRATEGY`	`RECOMMEND STRATEGY average_vector`; offline supports `best_score` and `sum_scores` only
`QQL-EDGE-UNSUPPORTED-POINT-REF`	Point-ID query inputs need materialized vectors offline
`QQL-EDGE-UNSUPPORTED-FIELD-TYPE`	The index field type is not available offline
`QQL-EDGE-UNSUPPORTED-ROUTE`	The planned operation has no edge route implementation (defensive fallback)
`QQL-EDGE-INVALID-POINT-ID`	Offline point IDs accept unsigned integers or UUIDs only

Edge also emits QQL-EDGE-* runtime failures for storage and configuration problems: collection lifecycle (QQL-EDGE-COLLECTION-EXISTS, QQL-EDGE-COLLECTION-NOT-FOUND, QQL-EDGE-DELETE-COLLECTION, QQL-EDGE-DELETE-COLLECTION-CLOSE, QQL-EDGE-CLOSE), storage I/O (QQL-EDGE-CREATE-DIR, QQL-EDGE-READ-DIR, QQL-EDGE-DIR-ENTRY, QQL-EDGE-LIB, QQL-EDGE-SPAWN, QQL-EDGE-CONFIG), vector handling (QQL-EDGE-VECTOR, QQL-EDGE-VECTOR-NAME-MISSING, QQL-EDGE-MISSING-VECTOR, QQL-EDGE-MULTI-VECTOR-NAMES, QQL-EDGE-FIELD-NAME), filters (QQL-EDGE-FILTER-CONVERT, QQL-EDGE-FILTER-SERIALIZE, QQL-EDGE-FILTER-DESERIALIZE), query conversion (QQL-EDGE-QUERY), embedding (QQL-EDGE-EMBED), and mutations that require a target (QQL-EDGE-DELETE-REQUIRES-TARGET, QQL-EDGE-CLEAR-PAYLOAD-REQUIRES-TARGET, QQL-EDGE-DELETE-PAYLOAD-REQUIRES-TARGET, QQL-EDGE-DELETE-VECTORS-REQUIRES-TARGET, QQL-EDGE-SET-PAYLOAD-REQUIRES-TARGET).

The Backend compatibility matrix covers which features are available on each backend.

Complete code set

The full set of codes emitted by the reference implementation, generated from rg -o 'QQL-[A-Z0-9-]+' crates/qql-core/src crates/qql-plan/src crates/qql-edge/src:

QQL-BACKEND
QQL-EDGE-CLEAR-PAYLOAD-REQUIRES-TARGET
QQL-EDGE-CLOSE
QQL-EDGE-COLLECTION-EXISTS
QQL-EDGE-COLLECTION-NOT-FOUND
QQL-EDGE-CONFIG
QQL-EDGE-CREATE-DIR
QQL-EDGE-DELETE-COLLECTION
QQL-EDGE-DELETE-COLLECTION-CLOSE
QQL-EDGE-DELETE-PAYLOAD-REQUIRES-TARGET
QQL-EDGE-DELETE-REQUIRES-TARGET
QQL-EDGE-DELETE-VECTORS-REQUIRES-TARGET
QQL-EDGE-DIR-ENTRY
QQL-EDGE-EMBED
QQL-EDGE-FIELD-NAME
QQL-EDGE-FILTER-CONVERT
QQL-EDGE-FILTER-DESERIALIZE
QQL-EDGE-FILTER-SERIALIZE
QQL-EDGE-INVALID-POINT-ID
QQL-EDGE-LIB
QQL-EDGE-MISSING-VECTOR
QQL-EDGE-MULTI-VECTOR-NAMES
QQL-EDGE-QUERY
QQL-EDGE-READ-DIR
QQL-EDGE-SET-PAYLOAD-REQUIRES-TARGET
QQL-EDGE-SPAWN
QQL-EDGE-UNSUPPORTED-ACORN
QQL-EDGE-UNSUPPORTED-ALTER
QQL-EDGE-UNSUPPORTED-COLLECTION-PARAMS
QQL-EDGE-UNSUPPORTED-CONSISTENCY
QQL-EDGE-UNSUPPORTED-FIELD-TYPE
QQL-EDGE-UNSUPPORTED-GROUP-BY
QQL-EDGE-UNSUPPORTED-POINT-REF
QQL-EDGE-UNSUPPORTED-RECOMMEND-STRATEGY
QQL-EDGE-UNSUPPORTED-ROUTE
QQL-EDGE-UNSUPPORTED-SHARD
QQL-EDGE-UNSUPPORTED-SHARD-KEY
QQL-EDGE-UNSUPPORTED-TIMEOUT
QQL-EDGE-VECTOR
QQL-EDGE-VECTOR-NAME-MISSING
QQL-JSON-NONFINITE
QQL-JSON-NUMBER
QQL-LEX-CHAR
QQL-LEX-STRING
QQL-PARSE-CLAUSE-ORDER
QQL-PARSE-COMPARISON
QQL-PARSE-CONTEXT
QQL-PARSE-CROSS-RERANK
QQL-PARSE-DUPLICATE-CTE
QQL-PARSE-DUPLICATE-KEY
QQL-PARSE-EMBED
QQL-PARSE-EMBEDDING
QQL-PARSE-EMPTY-STATEMENT
QQL-PARSE-ESCAPE
QQL-PARSE-EXPECTED
QQL-PARSE-FIELD
QQL-PARSE-FILTER
QQL-PARSE-FLOAT
QQL-PARSE-IDENTIFIER
QQL-PARSE-IN
QQL-PARSE-INDEX-TYPE
QQL-PARSE-INTEGER
QQL-PARSE-LITERAL
QQL-PARSE-MATCH-ANY
QQL-PARSE-NONNEGATIVE-INTEGER
QQL-PARSE-NUMBER
QQL-PARSE-OBJECT-KEY
QQL-PARSE-PAYLOAD-SELECTOR
QQL-PARSE-POINT-ID
QQL-PARSE-POINT-IDS
QQL-PARSE-POSITIVE-INTEGER
QQL-PARSE-PREFETCH
QQL-PARSE-QUERY-INPUT
QQL-PARSE-SAMPLE
QQL-PARSE-SELECTOR
QQL-PARSE-SEPARATOR
QQL-PARSE-STATEMENT
QQL-PARSE-STATEMENT-LIMIT
QQL-PARSE-SYNTAX
QQL-PARSE-TRAILING
QQL-PARSE-UPDATE
QQL-PARSE-VALUE
QQL-PARSE-VECTOR-KIND
QQL-PLAN-COLLECTION
QQL-PLAN-CROSS-RERANK-CANDIDATE
QQL-PLAN-CROSS-RERANK-CTE
QQL-PLAN-CROSS-RERANK-MODEL
QQL-PLAN-CROSS-RERANK-PREFETCH
QQL-PLAN-CROSS-RERANK-QUERY
QQL-PLAN-FUSION-PREFETCH
QQL-PLAN-PREFETCH-CTE
QQL-PLAN-PREFETCH-GROUP
QQL-PLAN-RERANK-PREFETCH
QQL-PLAN-RERANK-USING
QQL-PLAN-RRF-PARAMS
QQL-PLAN-RRF-WEIGHTS
QQL-PLAN-UNSUPPORTED-PREFETCH
QQL-PLAN-VECTOR-KIND
QQL-REST-CLIENT-SIDE
QQL-VALIDATION-ACORN-SELECTIVITY
QQL-VALIDATION-CONFIG
QQL-VALIDATION-CONSISTENCY
QQL-VALIDATION-CREATE-MODEL
QQL-VALIDATION-CROSS-RERANK-PREFETCH
QQL-VALIDATION-FEEDBACK-STRATEGY
QQL-VALIDATION-FILTER-INJECT
QQL-VALIDATION-FROM
QQL-VALIDATION-FUSION
QQL-VALIDATION-FUSION-PREFETCH
QQL-VALIDATION-GEO
QQL-VALIDATION-HYBRID
QQL-VALIDATION-ID-PREDICATE
QQL-VALIDATION-LIMIT-OVERFLOW
QQL-VALIDATION-MMR
QQL-VALIDATION-POINT-ID
QQL-VALIDATION-POINTS-CLAUSE
QQL-VALIDATION-PREFETCH
QQL-VALIDATION-PREFETCH-CTE
QQL-VALIDATION-RECOMMEND-STRATEGY
QQL-VALIDATION-RERANK-PREFETCH
QQL-VALIDATION-RERANK-USING
QQL-VALIDATION-SCORE
QQL-VALIDATION-SEARCH-PARAM
QQL-VALIDATION-UPSERT-ID
QQL-VALIDATION-USING
QQL-VALIDATION-VECTOR

The QQL-EDGE-UNSUPPORTED- prefix is the family marker used by the edge backend to classify capability rejections; individual codes always carry the full suffix. New codes may be introduced in a v1 minor release (see language/v1/spec/versioning.md), so treat this list as a snapshot of the current reference implementation.