Repository navigation
Error Codes query
github-actions[bot] edited this page Nov 17, 2026
·
3 revisions
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 |
Ultimate — v31.43.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference