Errors
Every error the reference parser and validator return, what triggers it, and how to fix it.
Errors arrive in two waves. Parse errors mean the text or JSON did not form a query; they carry a source position. Validation errors mean the query parsed but says something impossible, and are checked after the whole query is in hand.
The messages below are the exact strings, so searching for one you have been handed should land here.
Validation errors
Query
| Message | Cause |
|---|---|
query: match clause is required |
No MATCH expression. Every query needs one. |
query: limit must be positive |
LIMIT 0 or a negative value. Omit the clause instead. |
query: window must be positive |
Same, for WINDOW. |
Boolean composition
| Message | Cause |
|---|---|
and: requires at least 2 children |
A one-element and array. Usually a client that built the array in a loop. |
or: requires at least 2 children |
As above. |
not: requires exactly 1 child |
not takes a single expression, not a list. |
If you are generating queries, emit the bare clause when a list has one element rather than wrapping it — a bare clause object is a valid expression.
DISTANCE
| Message | Cause |
|---|---|
distance: anchor is required |
No anchor. |
distance: cannot specify both within and top_k |
Two different bounds; pick one. |
distance: within must be in [0, 1] |
within is a similarity floor, not a radius. |
distance: within must be a finite number |
NaN or an infinity. |
distance: invalid metric value |
Not cosine, euclidean or dot. |
DIRECTION
| Message | Cause |
|---|---|
direction: at least one toward anchor is required |
Empty toward. |
direction: cone must be between 0 and π |
cone is a half-angle in radians, not degrees and not a similarity. |
direction: cone must be a finite number |
NaN or an infinity. |
A cone of 45 is the common form of this — degrees, where radians were
wanted. 45° is about 0.785.
CONTRAST
| Message | Cause |
|---|---|
contrast: at least one attract anchor is required |
Empty or absent attract. repel alone is not a query. |
contrast: within must be in [0, 1] |
As for DISTANCE. |
contrast: within must be a finite number |
NaN or an infinity. |
Note that repel is optional — see CONTRAST.
Parse errors
Expected something else
| Message |
|---|
expected clause keyword |
expected DISTANCE, DIRECTION, or CONTRAST |
expected keyword |
expected duration |
expected integer after LIMIT |
expected integer after TOP |
expected number after CONE |
expected number after WITHIN |
expected number in vector literal |
expected string after NOT in namespace |
expected string or '[' for anchor list |
expected string or vector literal for anchor |
expected time unit (s, m, h, d, w) |
unexpected token |
unexpected token after query |
unexpected token after query usually means the optional clauses are out of
order. They must appear as NAMESPACE, then WINDOW, then LIMIT; anything
after LIMIT is trailing input.
Values
| Message | Cause |
|---|---|
namespace names do not support wildcards ('*') |
There is no pattern matching on namespace names. Enumerate them. |
vector element must be a finite number |
NaN or an infinity inside a vector literal. |
Limits
These are covered in full on limits.
| Message |
|---|
arena overflow: too many AST nodes (max 64) |
arena overflow: too many anchors (max 32) |
arena overflow: string buffer exhausted (max 4096 bytes) |
vector too large (max 4096 elements) |
too many anchors in list (max 8) |
too many namespace includes (max 8) |
too many namespace excludes (max 8) |
expression nesting too deep (max 128) |
Reserved words
All keywords are case-insensitive in the text syntax, and the JSON form uses lowercase keys exclusively.
MATCH AND OR NOT DISTANCE DIRECTION CONTRAST ATTRACT REPEL
WITHIN TOP CONE WINDOW NAMESPACE ALL GLOBAL LIMIT
A bare word where a value was expected is often one of these used as an unquoted anchor. Anchors are always quoted strings or vector literals.