Skip to content

Error Codes query

github-actions[bot] edited this page Nov 17, 2026 · 3 revisions

Error codes: @ultimat3/query

Part of Error codes: every code @ultimat3/query registers. x errors explain <CODE> --json prints the same row.

Code Means Typical cause Fix
X_CURSOR_VALUE_UNSUPPORTED a sort value cannot be carried in a cursor a read ordered by a column whose values are objects, or by a number that is NaN/±Infinity — a cursor is JSON, and Date and bigint are the only non-JSON types it tags and revives. Raised where the cursor is MINTED, not where one arrives: the mistake is the read's own orderBy, so no retry and no fresh first page repairs it orderBy('createdAt') — or orderBy('id'): a scalar column — and project the composite value into the row instead
X_LIVE_ORDER_COLLATION a live query is ordered by a text column the matcher cannot order as Postgres does the live matcher orders text by code point while Postgres orders it by the column's collation (en_US.utf8: apple < Banana), so a patched row lands where the next read does not put it and a full window evicts the wrong row. A query.live.order_collation warning in development and test, once per query, never thrown; staging and production are silent. A refusal at subscribe is planned for next name: text().collate('C') # on the ordered column, then x db gen "<table> <column> collate C" — or .orderBy('createdAt', 'desc').orderBy('id') on the live read
X_MATCHER_UNSUPPORTED the live matcher cannot evaluate this SQL incrementally a join, aggregate or unbounded predicate under live: true live: false and poll — or reshape the query to equality filters + orderBy + limit
X_QUERY_AUDIT_SINK_FAILED an audited read was refused because the audit sink rejected its record the sink threw on an allowed record; the rows were withheld auditSink: postgresAuditSink({ executor }) — in apps/<app>/runtime.ts, a sink that accepts the record; then retry the read
X_QUERY_AUDIT_SINK_MISSING a query declares audit: true and no audit sink is installed apps/<app>/runtime.ts names no auditSink; the read is refused before its input is parsed auditSink: postgresAuditSink({ executor }) — in export const runtime = { … }, apps/<app>/runtime.ts
X_QUERY_CACHE_TTL_INVALID a query declares a cache ttlMs no tier can hold cache: { ttlMs: Infinity }, 0, a negative value or NaN. Judged at query(), in the file that declared it, rather than on the first read: the tiers already refuse the value with X_CACHE_TTL_INVALID, so before this the mistake compiled, passed review, and made every read of that query fail permanently in production. The cause echoes the value rather than the query name — query() runs before defineApi() stamps a name, exactly as X_QUERY_INPUT_UNENCODABLE does cache: { ttlMs: 60_000 } — a positive whole number of milliseconds; or drop the cache block — "do not cache" is expressed by not declaring one
X_QUERY_COLUMN_UNSELECTED a read filters or sorts on a column its rows do not carry from(entity, rows).where({ … }), .compare() or .orderBy() names a column the provider's rows lack — a loader that selected slug and updatedAt and a query filtering on status. It answered [] in silence until 22.0.0: absent is not "not equal", it is a read the loader never made. A present column holding null is a value, and an empty provider judges nothing db.posts.select({ slug: true, status: true, publishedAt: true }) — select the column in the loader — or drop the filter the loader already applied
X_QUERY_DEPRECATION_INVALID a query declares a deprecation whose dates cannot be rendered a deprecated: { since, sunset } value that is not a date — the mirror of X_ACTION_DEPRECATION_INVALID, refused where the declaration is converted so every projection that reads it refuses the same value deprecated: { sunset: '2026-12-31T23:59:59Z' } — on the query, an ISO-8601 instant
X_QUERY_DOWNLOAD_INVALID a query declares a download it cannot serve query({ download }) was combined with a rows option (sql, live, single, rows, subscribes, cache, mcp), its handle is not a function, or its expiresInMs is not a whole number of milliseconds between 1 s and 1 h query({ input, policy, download: { expiresInMs: 300_000, handle: async ({ input, ctx }) => ({ body, contentType, filename }) } }) // no sql and no rows option beside download
X_QUERY_DOWNLOAD_ONLY rows were asked of a query that answers a file a download query was read for rows — called through sourceFor, .as(), .page(), .live(), explain or an MCP tool — and it has no sql to read them with await recording.url(input) # a download query mints its signed URL; await recording(input) is the file in-process
X_QUERY_DOWNLOAD_TOKEN_EXPIRED a download URL is past its expiry the _token on GET /_x/query/ was minted more than the query's download.expiresInMs ago await queryClient<Api['queries']>({ baseUrl }).<name>.url(input) # right before the request; or raise download.expiresInMs (at most 3_600_000)
X_QUERY_DOWNLOAD_TOKEN_INVALID a download URL carries a token this app did not mint for it the _token on GET /_x/query/ is malformed, was sealed under a key this process no longer holds, was minted for another query, or was minted for different input — a URL edited after it was minted await queryClient<Api['queries']>({ baseUrl }).<name>.url(input) # a fresh URL; request it unchanged
X_QUERY_DUPLICATE two queries registered under one name duplicated export x queries list --json — query names are globally unique: rename one of the two exports
X_QUERY_ETAG_INVALID etag: true on a read that has its own validator query({ etag: true }) on a download read or a live read — a download answers its own ETag, and a live read is revalidated by its cursor query({ input, policy, sql }) # the declaration the cause names, with etag: true removed; a live read's cursor is its validator
X_QUERY_FOREIGN a value that is not a query was projected as one a hand-rolled object with kind: 'query', or a query from a duplicated copy of @ultimat3/query export const name = query({ input, policy, sql }) — with query imported from @ultimat3/query
X_QUERY_HTTP_PATH_INVALID a query's pinned http.path is not a valid path template the pin is not a lowercase path of static or :param segments, claims /_x, repeats a :param, names a :param that is not a required string key of input:, or declares a method other than GET pin a template whose every :param is a required t.string key of input: — query({ input: t.object({ id: t.string }), http: { path: '/orders/:id' }, ... }) — never under /_x
X_QUERY_INPUT_UNENCODABLE a query input cannot be carried in a query string a read declaring a nested t.object/t.record/t.money member, an array or union of one, a REQUIRED t.nullable(...) member, or a top-level input that is not an object, or a member named _first or _after — the two page controls the route reads off the search string before the schema sees it. A read is served as GET /_x/query/<name>, so its input is characters: the typed client would encode a structure as JSON text and skip a null, and coerceQuery has no inverse for either. Raised at query(), in the file that declared it { status: t.string, limit: t.number } — flatten the key into scalar arguments, spell an absent value as .optional() rather than t.nullable(...), or declare it as an action() if it really needs a JSON body
X_QUERY_LIVE_UNBOUNDED a live query declares no limit, so its window is the whole table a query with live: true whose sql() returns a source with no .limit(): every subscriber would hold, and the matcher patch, every matching row append .limit(<n>) after the .orderBy(...) in the query's sql: callback (apps/web/app/<slice>/live/<name>.ts), or drop live: true
X_QUERY_MAX_PAGE_INVALID a query declares a maxPage no page bound can hold maxPage is not a whole number of rows from 1 to MAX_PAGE_SIZE (10,000) query({ maxPage: 2000 }) # a whole number from 1 to 10000 — or drop maxPage for the 500-row wire cap
X_QUERY_NOT_PAGEABLE a read returned rows with no id, so a cursor cannot name a position a projection or aggregate that drops the primary key — the id is the tiebreak that makes the sort order total select({ id: true, … }) — return the primary key from the query's sql:, e.g. db.posts.select({ id: true, … })
X_QUERY_POLICY_MISSING a query was registered without a policy same, for reads policy: can('<resource>:<verb>') — on the query, a permission your definePermissions() declares, never the query's own name; or policy: allow('public') for a public read (allow() takes a label, never a permission)
X_QUERY_SCOPE_UNCOMPOSABLE a scoped policy guards a read whose source cannot take its predicate the query's sql returns a hand-written SqlSource, not from(), so the policy's scope() has nowhere to be composed and the page would be cut before the rule filters it sql: (input) => from<Row>('<table>', (window) => repo.window(window)) — or drop scoped() from the query's policy
X_QUERY_SINGLE_INVALID a query declares single: as something other than a boolean generated code or a JS caller wrote single: "yes" or 1 single: true — for a read of one object; or drop the key for a list read
X_QUERY_SUBSCRIBES_DRIFT a live query subscribes to a relation its own sql never reads the declaration and the read disagree: subscribes: ['post'] while sql: returns from('posts', …). Thrown at the first subscribe, where the resolved QueryShape is the first thing that can say which relation the read really names — the string lives inside a callback nothing can invoke without valid input. A refusal and not a warning: a declaration that names the wrong relation is one its author reads as true subscribes: ['posts', '<relation>'] — add the relation the cause names, then x db gen
X_QUERY_SUBSCRIBES_INVALID a query declares subscribed relations no live read can use subscribes: [], or a subscribes: on a read that is not live: true. Judged at query(), in the file that declared it, like X_QUERY_CACHE_TTL_INVALID one field over — an empty list names no relation for the first subscribe to check, and a non-live read never reaches the cross-check at all, so an accepted one would be a declaration nothing verifies and nothing emits subscribes: ['posts'] — the relation the read selects from — or delete the field; on a read that should be subscribable, add live: true beside it
X_QUERY_TIMEOUT_INVALID a read declares a timeoutMs that is not a whole positive number of ms query({ timeoutMs }) is 0, negative, a fraction, NaN or Infinity, or is set on a download read query({ timeoutMs: 500 }) # a whole number of ms under the role bound, read with: psql "$DATABASE_URL" -c "show statement_timeout" — or drop timeoutMs
X_QUERY_UNREGISTERED a query was projected before it was registered .client() / .live() on a read no defineApi() named defineApi({ queries }) — in apps/<app>/api/index.ts, listing the query's module; the boot names it before serving reads

Clone this wiki locally