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

classstatuswhen
Unauthorized401a deploy, validate, test or removal without the server’s deploy token. Never a read: the query routes take no credential
NotFound404no deployment for the project and branch
Invalid400neither spec nor expr in the body
Shorthand400the expr did not parse
ContextRequired400the branch has policies and the request has no context
TooLarge400the body, or something in the spec, is over a request bound
DeployError400deploy or validate failed (not a query route)
InvalidSpec422the spec’s shape is wrong
InvalidValue422the spec is well-formed but a value fails validation; message prefixed Validation failed:
FieldNotFound422a field reference resolved to nothing
FieldAmbiguous422a name is both a dimension and a measure
Unresolvable422the planner cannot build the query from the model
SegmentDatasource422a segment keyed in another datasource; an internal retry signal, normally not surfaced
SecurityPolicy422a policy’s context dimension is unreachable from the query
Unimplemented422a feature the planner does not plan
Dialect500the base dialect failed to load
Busy503the server is running as much of this kind of work as it admits; carries Retry-After
Timeout503the 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

classmessage
Unauthorizedthis server takes a deploy token for deploys, tests and removals: Authorization: Bearer <token> ...
Unauthorizedthis deploy token is not valid
Busythe server is full of plan work: retry in 1s
Timeoutthis request passed its 30s deadline
NotFoundno deployment for project <uid> branch <branch>
Invalidgive a spec or an expr
ContextRequiredthis branch has security policies; a context is required to plan

Field references

classmessage
FieldNotFoundNo field named 'x' in this model. optionally followed by Did you mean: A, B, C?
FieldAmbiguousField '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)

messagecause
malformed spec: ...unknown key, wrong JSON type, or unparseable JSON anywhere in the spec
projection N needs a fielda non-calculation projection without field
'x' is not an order_by (asc, desc)bad order_by
Unknown decorator type: Xbad 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 Xbad 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: .

messagecause
Alias can't be blankcalculation 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 onlyaxis: tip on a dimension
X can only be applied to dimensionstruncate, extract or customize on a measure
only date/datetime types can be date truncatedtruncate or extract on a non-date dimension
Grain must be set, Extract must be set, Mode must be moving or running, Transform invalid transform typedecorator 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 fieldtop_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 numericnon-numeric value on a numeric field
<decorator> on <owner>: 'x' is not a projected dimension; partition and order refs name a dimension the query projectsa 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 dimensionthe 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

classmessage
UnresolvableAt least one projection required
UnresolvableNo universe can resolve the query within datasource D. The projected fields cannot be joined into one query from the model; see Universe formation.
UnresolvableCould not find path for X
Unresolvablecannot parse date ...
Unresolvablethe query's hints name no table: X — a hints entry that matches no table by uid or name, with the nearest names appended
Unresolvablethe query's hint X names 2 tables; say which by uid: a, b — a hint that matches by name where two tables share it
UnresolvableCalculation X references itself through Y
UnresolvableCould not resolve segment S: ...
SecurityPolicySecurity policy context dimension '<Name>' is not reachable in the universe for this query. Cannot safely enforce security policy.
Unimplementednot implemented: custom predicate
Unimplementedcalculations 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:

messagecause
nothing to planan 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 bracketeda name followed by ( that is not a function
after `and`, expected `field predicate value`; a value holding and/or is single-quotedan unquoted value containing and or or
a value is single-quoted; double quotes name a fielda double-quoted value
a list value cannot hold a comma: the spec joins the list with commas and the planner splits it againa quoted comma inside in (...) or keyword (...)
top needs a count, as in `category top 10 by revenue`; a name holding `top` is bracketedtop without an integer
write != instead of not =not before a predicate that does not negate
the spec has no `not between`; write two comparisonsnot between
a moving frame holds at least two rows: the current one and one beforemoving_avg(x, 1)
limit needs a whole number of rowsa non-integer limit
after the comma in calc(...), expected a result type: one of string, integer, decimal, date, date_time, boolean, biginta top-level comma inside calc( not followed by a type
calc( is never closed, the ' is never closedan unbalanced opener, reported at the column it opened
the alias is given twicea repeated as or asc/desc on one projection
expected @d or @m after the namean @ 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:

constantvalueeffect
MIN_LEN4references shorter than four characters are never corrected
FLOOR0.5the best candidate must score at least this
MARGIN0.2and 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}]}
keymeaning
termwhat the request said
field_uid, field_namewhat was used
scorethe 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 line8 KB
projections100
calculations50
segments50
filters, and nesting depth200, 8
values in one spec, and nesting depth20,000, 32
one string in a spec64 KB
a q search term200 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 on message. Messages name fields and may change wording.
  • Surface FieldNotFound with its Did you mean candidates and FieldAmbiguous with its @d/@m hint directly to whoever is building the query; they are written to be shown.
  • Log corrections with the request. A rename in the model can turn an exact match into a fuzzy one without any error.

Next steps