Errors and corrections
Every failure is JSON with one shape, and the class tells you whose fault it is: the envelope, the spec, the model, or the server. Successful responses may also carry a corrections array when a misspelled field was silently matched. This page lists both so your application can act on them.
The envelope
{"error": {"class": "FieldNotFound", "message": "No field named 'revenu' in this model. Did you mean: Revenue, Net Paid?"}}
class is stable and meant for code; message is for people and may name fields from the model.
Classes and statuses
| class | status | when |
|---|---|---|
Unauthorized | 401 | a deploy, validate, test or removal without the server’s deploy token. Never a read: the query routes take no credential |
NotFound | 404 | no deployment for the project and branch |
Invalid | 400 | neither spec nor expr in the body |
Shorthand | 400 | the expr did not parse |
ContextRequired | 400 | the branch has policies and the request has no context |
TooLarge | 400 | the body, or something in the spec, is over a request bound |
DeployError | 400 | deploy or validate failed (not a query route) |
InvalidSpec | 422 | the spec’s shape is wrong |
InvalidValue | 422 | the spec is well-formed but a value fails validation; message prefixed Validation failed: |
FieldNotFound | 422 | a field reference resolved to nothing |
FieldAmbiguous | 422 | a name is both a dimension and a measure |
Unresolvable | 422 | the planner cannot build the query from the model |
SegmentDatasource | 422 | a segment keyed in another datasource; an internal retry signal, normally not surfaced |
SecurityPolicy | 422 | a policy’s context dimension is unreachable from the query |
Unimplemented | 422 | a feature the planner does not plan |
Dialect | 500 | the base dialect failed to load |
Busy | 503 | the server is running as much of this kind of work as it admits; carries Retry-After |
Timeout | 503 | the request passed its deadline (30 seconds; 90 for a deploy); no Retry-After |
400 means fix the request envelope; 422 means fix the spec or the model; 503 Busy means wait the seconds Retry-After names and send it again; 500 is ours. There is no 403 and no 429: who may ask, and how often, is decided by the service you put in front of the server.
Messages you will meet
Envelope
| class | message |
|---|---|
Unauthorized | this server takes a deploy token for deploys, tests and removals: Authorization: Bearer <token> ... |
Unauthorized | this deploy token is not valid |
Busy | the server is full of plan work: retry in 1s |
Timeout | this request passed its 30s deadline |
NotFound | no deployment for project <uid> branch <branch> |
Invalid | give a spec or an expr |
ContextRequired | this branch has security policies; a context is required to plan |
Field references
| class | message |
|---|---|
FieldNotFound | No field named 'x' in this model. optionally followed by Did you mean: A, B, C? |
FieldAmbiguous | Field 'x' is ambiguous — more than one field answers to it. Use x@d or x@m to pick the dimension or the measure. |
Spec shape (InvalidSpec)
| message | cause |
|---|---|
malformed spec: ... | unknown key, wrong JSON type, or unparseable JSON anywhere in the spec |
projection N needs a field | a non-calculation projection without field |
'x' is not an order_by (asc, desc) | bad order_by |
Unknown decorator type: X | bad decorator type |
unknown attribute 'x' on the <type> decorator of <owner> | attribute not in the decorator vocabulary |
'X' is not a predicate (filter on F) | bad predicate name |
filters must be an array or a logic tree, got ... | bad filters type |
a filter node needs a field or an and/or key, got X | bad tree node |
Filters here are a flat AND list — each entry must name a field; and:/or: groups are not supported in this position. ... | an and/or group inside an array |
Segment 'X' has no definition — ..., Segment 'X' needs at least one key dimension — ..., Unknown segment mode 'x' — use include or exclude, apply_to: no measure projection matches 'x' ..., apply_to: 'x' matches multiple projections — ..., join applies only to expanding segments — ... | segment rules, listed in full on Segments |
Validation (InvalidValue)
All prefixed Validation failed: .
| message | cause |
|---|---|
Alias can't be blank | calculation without an alias |
Sql can't be blank (calculation 'X') | calculation without a formula |
Sql columns like x,y are not permitted in calculations. | bare identifiers in a formula; use [Name]@m / [Name]@d |
Sql could not find a projection with alias X. If you meant to references a measure or dimension used @m or @d to clarify: [My Measure]@m | [Alias] that matches no projection |
Axis the tooltip holds measures only | axis: tip on a dimension |
X can only be applied to dimensions | truncate, extract or customize on a measure |
only date/datetime types can be date truncated | truncate or extract on a non-date dimension |
Grain must be set, Extract must be set, Mode must be moving or running, Transform invalid transform type | decorator missing its required attribute |
Predicate <Name> predicate is not supported for <Field>. | predicate not allowed on that field type |
Predicate top n can only be applied to a dimension field | top_n on a measure |
Filter value can't be blank (<predicate> on <field>) | missing filter value |
Filter value is not a number, Filter value values must be numeric | non-numeric value on a numeric field |
<decorator> on <owner>: 'x' is not a projected dimension; partition and order refs name a dimension the query projects | a partition_refs entry or window order_by key that no projected dimension answers to by uid, name or display alias |
<decorator> on <owner>: 'x' is a measure; a window partitions and orders only by a projected dimension | the same, where the name is a projected measure or calculation |
A bad calculation data_type (outside string, integer, decimal, date, date_time, boolean, bigint, binary) and a window size, offset or buckets below 1 are rejected in the same class.
Planner
| class | message |
|---|---|
Unresolvable | At least one projection required |
Unresolvable | No universe can resolve the query within datasource D. The projected fields cannot be joined into one query from the model; see Universe formation. |
Unresolvable | Could not find path for X |
Unresolvable | cannot parse date ... |
Unresolvable | the query's hints name no table: X — a hints entry that matches no table by uid or name, with the nearest names appended |
Unresolvable | the query's hint X names 2 tables; say which by uid: a, b — a hint that matches by name where two tables share it |
Unresolvable | Calculation X references itself through Y |
Unresolvable | Could not resolve segment S: ... |
SecurityPolicy | Security policy context dimension '<Name>' is not reachable in the universe for this query. Cannot safely enforce security policy. |
Unimplemented | not implemented: custom predicate |
Unimplemented | calculations over rule-bearing measures, inclusion sub-plan outside the node's universe |
Expression parse errors (Shorthand, 400)
Every message from the expression language ends in the position it was raised at: (column N) on one line, (line N, column N) on several. Columns count characters, not bytes. A representative set:
| message | cause |
|---|---|
nothing to plan | an expr with no items |
`Is` is a reserved word and cannot start a name; write [Is Active] or "Is Active" | one of the fourteen reserved words inside a bare name |
unknown function `monthly`; the help lists the functions, and a field whose name holds a parenthesis is bracketed | a name followed by ( that is not a function |
after `and`, expected `field predicate value`; a value holding and/or is single-quoted | an unquoted value containing and or or |
a value is single-quoted; double quotes name a field | a double-quoted value |
a list value cannot hold a comma: the spec joins the list with commas and the planner splits it again | a quoted comma inside in (...) or keyword (...) |
top needs a count, as in `category top 10 by revenue`; a name holding `top` is bracketed | top without an integer |
write != instead of not = | not before a predicate that does not negate |
the spec has no `not between`; write two comparisons | not between |
a moving frame holds at least two rows: the current one and one before | moving_avg(x, 1) |
limit needs a whole number of rows | a non-integer limit |
after the comma in calc(...), expected a result type: one of string, integer, decimal, date, date_time, boolean, bigint | a top-level comma inside calc( not followed by a type |
calc( is never closed, the ' is never closed | an unbalanced opener, reported at the column it opened |
the alias is given twice | a repeated as or asc/desc on one projection |
expected @d or @m after the name | an @ suffix that is neither |
An expr that is missing entirely, or empty, is Invalid rather than Shorthand: give a spec or an expr. Everything that needs the model — a name that is not a field, a decorator on the wrong kind, a partition reference that is not projected — parses fine and fails at 422 instead.
The corrections array
A field reference that matches nothing exactly is scored against every field of the wanted kind by trigram overlap of the normalized text (lower-cased, runs of non-alphanumerics collapsed to one space) against the field’s name, uid and synonyms. Three constants decide what happens:
| constant | value | effect |
|---|---|---|
MIN_LEN | 4 | references shorter than four characters are never corrected |
FLOOR | 0.5 | the best candidate must score at least this |
MARGIN | 0.2 | and lead the runner-up by at least this |
When both hold the candidate is used silently and the response reports it:
{"sql": "...", "datasource": "Warehouse", "datasource_uid": "warehouse", "adapter": "postgres",
"corrections": [{"term": "departmnt", "field_uid": "department", "field_name": "Department", "score": 0.8}]}
| key | meaning |
|---|---|
term | what the request said |
field_uid, field_name | what was used |
score | the overlap, rounded to two decimals |
corrections is omitted when empty. When the floor or the margin is not met, the request fails with FieldNotFound and up to three candidates scoring at least 0.25 in Did you mean: A, B, C?.
zsql prints corrections to stderr before the SQL, one per line:
departmnt → Department (~0.8)
Treat a correction as a warning in an interactive tool (show the user what was substituted) and as an error in a pipeline, where a silently substituted field is a bug waiting to be noticed.
Request bounds
Each refusal is a 400 TooLarge naming the limit.
| limit | |
|---|---|
| request body (every query route) | 1 MB |
expr line | 8 KB |
| projections | 100 |
| calculations | 50 |
| segments | 50 |
| filters, and nesting depth | 200, 8 |
| values in one spec, and nesting depth | 20,000, 32 |
| one string in a spec | 64 KB |
a q search term | 200 characters |
These bound what one request can cost. They are not rate limits: the server has none, and pacing callers belongs to the service in front of it.
Handling errors in your app
async function plan(body) {
const res = await fetch(`http://127.0.0.1:3699/projects/tpcds/branches/main/sql`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
const json = await res.json();
if (!res.ok) {
const { class: cls, message } = json.error;
switch (cls) {
case "FieldNotFound":
case "FieldAmbiguous":
case "InvalidSpec":
case "InvalidValue":
case "Shorthand":
throw new UserFixable(message); // show it; the request can be edited
case "Unresolvable":
case "SecurityPolicy":
case "Unimplemented":
throw new ModelProblem(message); // the model or the policy needs a change
case "ContextRequired":
case "Invalid":
case "NotFound":
throw new IntegrationBug(cls, message); // your code built the request wrong
case "Busy":
throw new RetryLater(res.headers.get("Retry-After")); // the server is full; wait and resend
default:
throw new Error(`${cls}: ${message}`); // 5xx: report it
}
}
if (json.corrections?.length) {
log.warn("0sql corrected fields", json.corrections);
}
return json; // { sql, datasource, datasource_uid, adapter, ... }
}
Three habits that pay off:
- Branch on
class, never onmessage. Messages name fields and may change wording. - Surface
FieldNotFoundwith itsDid you meancandidates andFieldAmbiguouswith its@d/@mhint directly to whoever is building the query; they are written to be shown. - Log
correctionswith the request. A rename in the model can turn an exact match into a fuzzy one without any error.