Common Query Errors (v2)

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):

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

A _delete / _modify where reads the collection's own fields. A field it does not have — a link path such as cust.tier, or a typo — is a 400 whose message names the field. Select the rows with a _query on the link path, then change them by their own key.

Failures that aren't domain-specific — an unauthorised key, a wrong method, a quota refusal — carry the envelope too, with a code named after the status: unauthorized (401), forbidden (403), method_not_allowed (405), conflict (409), payload_too_large (413), unsupported_media_type (415), rate_limited (429), unavailable (503). A refusal that carries extra machine-readable facts keeps them beside code and message — a free-tier row-quota refusal, for instance, adds limit, table and hint under data.

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.

These shapes do not depend on how the table is stored. _estimate, _aggregate and _evaluate run different implementations for a rep2 collection and a legacy rep1 table, but both answer in the {kind, data} frame. Where the legacy path names a payload field the way v1 did, the v2 name is added alongside it: _estimate returns both data.value and data.estimate holding the same number, so data.value is always safe to read.

401 or 415 on a POST: the two headers every POST needs

Every POST needs two headers, and each has its own status when it is missing:

• x-api-key missing, or a key the server does not know: 401, on every route and method (see 401 / 403).
• content-type: application/json missing or different: 415, whose message starts Content-Type must be application/json and names the header to send. curl -d sends application/x-www-form-urlencoded unless you say otherwise, so this is the usual cause. On /api/v2 the body is the v2 error envelope with the code unsupported_media_type.

If both headers are missing, the key is checked first, so the answer is 401; fix the key, and the next request answers 415 until the content type is set.

Fix: send both headers on every POST:

curl -X POST 'https://shared.aito.ai/db/aito-demo/env/v2/api/v2/_query' \
  -H 'x-api-key: yg4rTlXkqDzm4y8gPeY75HCKaNwfbTQ2si64ONTi' \
  -H 'content-type: application/json' \
  -d '{ "from": "products", "limit": 1 }'

Against a local Docker container, the URL is http://127.0.0.1:9005/api/v2/_query and the key is your READ_WRITE_APIKEY (see Docker).

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)

The status says which of two things is wrong, on every route and method alike:

• 401 — fix your key. "The required header 'x-api-key' is missing" (no key sent) or "The API key you provided is not recognised" (not a key of this database — a typo, a rotated key, or a key of another database).

• 403 — this key can't do that. "not authorized to perform this operation": a real key without the permission — almost always a read-only key on a write (PUT/DELETE schema, POST .../_batch). Reads succeed, writes 403 — use a read-write key. On the Docker image, the read-only key is APIKEY and the read-write key is READ_WRITE_APIKEY; a write with the read-only key returns 403 with the code forbidden.

  Available since: v2.11.2. Up to v2.11.1 a missing key answered 400 on a GET and 405 "method not allowed, supported methods: GET" on a POST/PUT/DELETE; an unknown key 403 or 405; and a read-only key on a write 401.

• 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).

Collection written by an older binary format

Error: 409 — This collection was written in binary format N, but this Aito build reads format M. …, or Env '<name>' is stored in an older on-disk format and is being migrated in the background … retry shortly. On builds up to v2.8.0 the same situation surfaced as a 500 carrying a raw internal error such as slice [1090930175543, …] out of bounds or ListSeqRepIoType expected 8 entries in OrderDir, got 6 — a message about the decoder, on a query that has nothing to do with formats.

Cause: the collection's on-disk state was written by an older Aito build whose binary format has since changed. master migrates at server start; an env branch migrates the first time you use it, so the first request against a not-yet-migrated branch starts the rebuild and is refused while it runs. A state that arrives mid-session — typically an env restored from an older backup — behaves the same way. See server upgrades and env branches.

Fix: retry. The migration is already running in the background and the same request succeeds once it finishes; a large branch takes longer. Use POST /api/v2/data/{table}/repair (once per collection in that env) when you would rather rebuild immediately than wait, or if a migration reported a failure. Only rep2 collections are affected; rep1 type: "table" tables have their own versioning and migrate at open.

Write contention: 409 write.contention

Error: 409 with the code write.contention and a Retry-After header — a positional write re-anchored 64 times without committing: concurrent writes kept moving the table; retry the request.

Cause: a large write that resolves its rows first and commits second — a _delete that matches many rows, or a keyed upsert of many rows — met a table that other writers had changed in between, re-resolved, and lost the race again on every attempt. It happens when a steady stream of small writes lands on the same table during one large write. Nothing was written: the request either commits whole or not at all.

Fix: retry the same request. It is safe: a write.contention answer means nothing was committed, so the retry cannot apply the write twice.

• Key on the code, not on 409 alone. Other 409s mean something else: an env being migrated (retry later), a collection in an older binary format (needs a repair, not a retry), a release that already exists. Retry automatically only on write.contention.
• Back off with jitter. Treat Retry-After as the minimum wait, then grow the wait on each attempt and add a random component (e.g. full jitter: wait a random time between Retry-After and an exponentially growing cap). Under heavy write churn, many clients retrying on a fixed one-second beat keep colliding with each other. Give up after a few attempts.
• If it keeps happening, pause the small writers to that table for the duration of the large write, or split the large write into smaller batches.

Over the PostgreSQL interface the same condition is SQLSTATE 40001 (serialization failure), which database drivers and ORMs already retry.

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": { "$match": "coffee" } } }

Strict tables reject it; flexible collections match nothing

Whether an unknown where field is an error or a silent empty result depends on the schema policy of what you are querying:

The flexible case is the one that costs debugging time: a typo returns a perfectly valid empty result, indistinguishable from "nothing matched". If a query on a collection returns total: 0 unexpectedly, check the field names against GET /api/v2/schema/{table} before assuming the data is missing.

A dotted path is different on both kinds of table: a path that does not resolve through the schema — a segment the linked table does not have, or a hop through a field that is not a link — is a typo in the path, not a column no row has yet, so it is refused with 400, naming the segment that failed and the fields available at that hop:

where: no such path 'company_id.NOPE': 'NOPE' is not a field of 'company_id'; its fields are: company_id, industry, name.

The same holds for a misspelt column inside a $refs filter ({ "$refs.contacts.company_id": { "$exists": { "rol": "CTO" } } } names rol and the referring table). select and orderBy already refused an unresolvable path.

On v2.11.0 and earlier a path cannot continue through a self-link (a column whose link is this.<key>, such as prev → this.id): prev.user.tags is refused the same way, naming prev. Filter on the self-link's own value instead. Since v2.11.2, a path traverses self-links; see Multi-hop paths.

Unknown table

Error: 404 with the code not_found. A query names the table in the message ("invoicess not found"); the data and schema endpoints say "No such table: invoicess":

{ "kind": "error", "data": { "code": "not_found", "message": "invoicess not found" } }

It is usually a misspelt name, or a query sent before the table was created. On a fresh local container no table exists yet, so a copied _predict fails this way until you create the table and insert rows.

• 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 errors

POST /api/v2/_similarity exists in v2. Earlier versions of this page said it returns 404; it does not. A mistake in the body is a 400 that names the problem, for example missing 'from' (table name) for an empty body. A 404 with "code": "not_found" means the path itself is wrong, such as a typo in the endpoint name.

A valid call names the table and a {field: text} probe to rank rows against:

POST /api/v2/_similarity
{
  "from": "products",
  "similarity": { "name": "lactose free milk" },
  "select": ["name", "$score"],
  "limit": 3
}

{
  "offset": 0,
  "total": 42,
  "hits": [
    { "$score": 8.28, "name": "Pirkka lactose-free semi-skimmed milk drink 1l" },
    { "$score": 7.31, "name": "Valio eila™ Lactose-free semi-skimmed milk drink 1l" },
    { "$score": 1.91, "name": "Pirkka Finnish nonfat milk 1l" }
  ]
}

To combine similarity with other conditions, rank by it inside an ordinary query with orderBy, next to any where:

{
  "from": "products",
  "where": { "price": { "$lt": 3 } },
  "orderBy": { "$similarity": { "name": "coffee" } },
  "limit": 10
}

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": { "$match": "coffee" }, } }
// Correct
{ "from": "products", "where": { "name": { "$match": "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.

Related

• 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.