Common Query Errors (v2, Beta)

This page describes common errors on the v2 API and how to resolve them. A theme runs through v2: it fails loud. Conditions that a lenient API might turn into an empty result — an unsupported operator, an unknown config profile, a missing test set — return a 4xx with a message instead, because an empty result is indistinguishable from "no match" and hides the real problem.

The error response format

Every v2 error — from any endpoint, at any status — returns the same JSON envelope, so a client can parse errors one way across the whole API:

{
  "kind": "error",
  "data": {
    "code": "not_found",
    "message": "Unknown table 'invoicess'"
  }
}

kind is always the literal string "error" — the cheapest check for "did this request fail" (independent of the HTTP status).
data.code is a stable, machine-readable code (a dotted namespace) — branch on this in an SDK. Codes are contractual; the message wording is not.
data.message is a human-readable, single-line explanation — surface it, but don't parse it.

The HTTP status carries the coarse class (4xx client, 5xx server); the code carries the specific cause. For an SDK, the reliable pattern is: if the body has "kind": "error", read data.code; otherwise treat the body as a normal result.

Code catalogue

Query and read endpoints (_query, _search, _predict, _recommend, _relate, _aggregate, _estimate, _evaluate, _sql, _batch):

`code`	HTTP	Cause
`query.invalid`	400	The query shape is wrong — a bad `from`, an unrecognised structure.
`request.invalid`	400	A value failed validation (bad type, out-of-range argument).
`proposition.unsupported`	400	A `$`-operator isn't applicable to the named field.
`json.malformed`	400	The request body isn't valid JSON.
`not_found`	404	A referenced table (the `from`, or a linked table) doesn't exist.
`operation.unsupported`	501	A capability isn't implemented for this table/engine (e.g. a rep2-only operator on a legacy rep1 table). Distinct from `500` — "not supported here", not "we crashed".
`internal`	500	An unexpected server error. Report it.

Data-write endpoints (_delete, _modify, .../batch, .../stream, .../import) and schema endpoints add:

`code`	HTTP	Cause
`data.bad_request`	400	A write was rejected (e.g. a vector dimension mismatch, or `on_conflict` on a keyless table).
`import.failed` · `table.exists` · `schema.not_collection`	400	Import problems: the import failed, the target table already exists, or it isn't a `collection`.
`schema.create_failed` · `schema.column_update_failed` · `schema.refresh_failed` · `schema.plan_failed` · `schema.apply_failed`	400	The schema operation was rejected (the `message` says why).
`not_found`	404	The named table/column doesn't exist.

Two things this table makes explicit and worth relying on: a typo'd table name is a 404, not a 500 (it reads as "you referenced something missing", not "we crashed"), and an unsupported operation is a 501, not a 500 — so a client can tell "this engine can't do that" apart from a genuine bug.

Success responses

For contrast, successful responses come in two shapes:

Row results (_search, _predict hits, filtered _query) return the v1-compatible body { "offset": …, "total": …, "hits": [ … ] } — no kind field (an absent kind means rows).
Non-row results (_aggregate, _estimate, _evaluate, _batch) use the same { "kind": …, "data": … } frame as errors — e.g. { "kind": "aggregate", "data": { … } }. So the presence of "kind": "error" — never just the presence of kind — is what marks a failure.

401 / 403 — authentication and environments

Almost every auth failure on v2 is one of two things: wrong addressing or a read key used for a write.

There is no env-scoped API key. The same key that reads or writes master reads or writes every environment. An environment is selected purely by URL path — never by a dot suffix, a request-body field, a query parameter, or a header:

✅  /db/{db}/env/{name}/api/v2/_query      (multi-tenant server)
✅  /env/{name}/api/v2/_query              (single-db server)
❌  /db/{db}/env.{name}/api/v2/_query      (dot — not an env selector)
❌  body: { "env": "{name}", ... }         (ignored)

401 "not authorized to perform this operation" on a write (PUT/DELETE schema, POST .../_batch) almost always means a read-only key. Reads succeed, writes 401 — use a read-write key.
403 / 401 on an env path that reads fine on master is almost always an addressing bug — a dot instead of /env/, or a gateway rewriting the path. Confirm the env exists with GET /db/{db}/api/v2/_envs, then address it with the slash form above.

501 — `$patterns` / relate on a legacy table

Error: 501 — relate $patterns "supported on collections only".

Cause: the v2 _relate $patterns (itemset mining) endpoint requires a rep2 CollectionDb. Tables uploaded through the v1 API are legacy rep1 TableDb, and the v2 endpoint returns 501 for them by design. Two ways forward:

Mine now, no rebuild: hit the legacy endpoint POST /api/v1/_relate — it mines rep1 tables today.
Everything on v2: re-upload the table as a "type": "collection" (see Schema Migration).

Unknown field

Error: Unknown field 'fieldName' in table 'tableName'

Cause: the field name doesn't exist in the table schema.

Field names are case-sensitive — check the spelling.
Verify available fields: GET /api/v2/schema/{table}.
For linked fields use dot notation: product.name, not productName.

// Wrong — field doesn't exist
{ "from": "products", "where": { "productName": "coffee" } }
// Correct
{ "from": "products", "where": { "name": "coffee" } }

Unknown table

Error: Unknown table 'tableName'

Table names are case-sensitive.
List tables: GET /api/v2/schema.
Ensure the table was created before querying.

Type mismatch

Error: Type mismatch: expected 'expectedType', got 'actualType'

Use the JSON type the column declares:

// Wrong — price is a number column
{ "from": "products", "where": { "price": "3.95" } }
// Correct
{ "from": "products", "where": { "price": 3.95 } }

Strings for Text/String, numbers for Int/Decimal, true/false for Boolean, arrays for Array/Set.

`_similarity` returns 404

Error: 404 Not Found on POST /api/v2/_similarity.

Cause: v2 deliberately does not expose a _similarity endpoint. Similarity is an in-query operator, not a separate dispatch surface — which is strictly more flexible, because $similarity composes with any other filter.

// v1 style — no v2 endpoint
POST /api/v2/_similarity   ← 404

// v2 — use the $similarity operator inside a query
{
  "from": "products",
  "orderBy": { "$similarity": { "name": "espresso machine" } },
  "limit": 10
}

Use $similarity in orderBy, select, or where.

No test set on collection evaluate

Error: 400 — evaluate on a collection with neither test nor testSource.

Cause: unlike v1 tables, a v2 collection evaluate has no implicit default test set. Omitting both is rejected rather than silently sampling 100 rows, so you never measure something you didn't scope.

// Wrong — nothing scopes the test set
{ "evaluate": { "from": "products", "predict": "category" } }
// Correct — a deterministic 20% fold
{ "test": { "$index": { "$mod": [5, 0] } },
  "evaluate": { "from": "products", "where": { "name": { "$get": "name" } },
                "predict": "category" } }

See the Evaluation guide (v2).

Unknown inference profile

Error: 4xx — Unknown config.ai profile 'name'.

Cause: config.ai accepts fast (flat), and (v1), group (v2, the default), and high. An unrecognised name is rejected loudly, never silently ignored — so a typo can't quietly downgrade your inference.

// Wrong
{ "from": "products", "predict": "category", "config": { "ai": "groupp" } }
// Correct
{ "from": "products", "predict": "category", "config": { "ai": "group" } }

Unsupported computed column

Error: 4xx describing the unsupported expression.

Cause: a computed / derived column expression that the v2 engine doesn't support fails loud rather than resolving to an empty value. This is by design — a silent empty here would read as "no match" and mask the real cause.

Empty candidate set

Error: Empty candidate set / No matching rows.

Your filters matched nothing:

Broaden the criteria, or verify the filtered values exist.
Use $match for fuzzy text instead of exact match:

// Exact match may return nothing
{ "from": "products", "where": { "name": "coffee" } }
// Fuzzy
{ "from": "products", "where": { "name": { "$match": "coffee" } } }

Empty $search / $knn. Multi-term $search and $knn/$nn match all query tokens (AND). A term that appears in no row empties the whole result — near: "organic milk" returns nothing if "organic" is in no name, and $search "return policy refund" returns nothing if no single row has all three. Use OR or single terms ("$search": "return OR refund"), or the ranked search block, which orders by relevance instead of requiring every token: { "from": "prompts", "search": { "field": "prompt", "text": "refund" } }. Note that $search/$knn apply only to tokenized Text columns, not exact String columns.

Unknown operator

Error: Unknown operator '$operatorName'

Operators are case-sensitive and start with $.
Common v2 operators: $match (full-text), $has (Set/Array contains), $gt/$gte/$lt/$lte, $and/$or/$not, $numeric, $similarity, $get, $context, $why.
See the Query Operator Reference (v2).

Invalid JSON syntax

Error: Invalid JSON at line X, column Y

Usual suspects: missing commas, trailing commas, single quotes, unquoted strings, unbalanced brackets.

// Wrong — trailing comma
{ "from": "products", "where": { "name": "coffee", } }
// Correct
{ "from": "products", "where": { "name": "coffee" } }

Query timeout

Error: Query timeout / Request timeout

Add limit to bound the result set.
Use more specific where conditions.
After heavy writes, optimize the table and warm it — see Warming Strategies (v2).

`_predict` returns a flat / uniform distribution

Not an error, but a common surprise: every candidate comes back at ~1/N (e.g. 0.02 across 50 values). The evidence isn't discriminating — usually a high-cardinality target with only a few examples per value and only diffuse text signal, so there isn't enough per-value evidence to move off the prior.

For open-ended "which known answer / article / template", use ranked search retrieval over the resolved history instead of predict (see Support Triage).
Reserve predict for lower-cardinality targets (type, category, route, assignee) where each class has many examples.
Add "$why" — if the factor tree shows only a base rate and no evidence factors, the evidence was below the detection threshold.

Values look wrong after an engine upgrade

If a column reads back implausibly — a boolean that's all-true, a text column that lost its analysis, links that resolve empty — the data may have been ingested by a build that predated the relevant fix. Some fixes are on the write path and do not repair already-stored data. Re-ingest the environment and re-check before assuming a live engine bug.

Limits & Timeouts (v2) — request size, the 15-minute request timeout, pagination, _batch fail-fast semantics, and the 429 backpressure model.
Destructive operations & data-loss safety — why a dropped /env/{name}/ segment silently writes to production, and how to avoid it.
Query Operator Reference (v2) · Inference (v2) · Evaluation (v2)
v1 Common Errors — the classic-API version.