Repository navigation
Error Codes entity
github-actions[bot] edited this page Nov 16, 2026
·
2 revisions
Part of Error codes: every code @ultimat3/entity registers. x errors explain <CODE> --json prints the same row.
| Code | Means | Typical cause | Fix | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
X_AGGREGATE_MIXED_CURRENCY |
an amount was aggregated across currencies | 100 JPY and 100 EUR have no common unit, so a sum, min or max over them answers a number in no currency at all. Both drivers count the distinct currencies of the rows they are about to aggregate and refuse past one, rather than answering in whichever came first; the cause lists every currency it found. One currency at two scales is the same refusal with its own words and its own fix — the cause says 2 scales of USD, and a currency filter would keep both rows |
<entity>.andWhere('<col>.currency', 'eq', '<CUR>').<fn>('<col>') — one currency per call — or countBy('<col>.currency') first to see the split. For a scale mix: for await (const rows of <entity>.inBatches(1000)) { … }, folding at one scale in the app |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_AGGREGATE_UNSUPPORTED |
that column has no aggregate both drivers can answer alike | three conditions, one code, and the cause names which. A text column has no min/max the two drivers agree on — ordering is the database's collation in one and JS code-unit order in the other. avg over money is refused outright: the mean of an integer number of minor units is not one, so every answer would be a silent rounding. And a money sum past ±2^53 minor units has no JS number to hold it, and MoneyValue.minor is one |
the fix names the exact call. For a wrong column, <entity>.<fn>('<candidate>') — the cause lists the columns that fn accepts, or says the entity declares none. For avg over money, <entity>.sum(col) and <entity>.count(), dividing at the call site where the rounding is a decision somebody made. For the overflow, narrow the rows with .andWhere(…)
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_APPROXIMATE_COUNT_FILTERED |
an estimate was asked of a filtered chain |
approximateCount() reads reltuples out of pg_class, which knows nothing about a predicate, so posts.where({ orgId }).approximateCount() would answer for the whole TABLE while reading as "roughly how many of mine". Refused rather than answered, because the wrong answer is plausible and unbounded |
<entity>.count() — the exact answer for a filtered chain. approximateCount() answers for the whole table only |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_DRIVER_CAPABILITY_MISSING |
a custom driver declares a capability its raw repo does not implement | defineDriver({ capabilities }) names a capability (meta.capability) whose method the repo() factory does not return, or transactions with no transactor() | add the method the cause names to the object repo() returns in defineDriver({ … }), or drop the capability from capabilities |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_DRIVER_ROW_OUT_OF_SCOPE |
a custom driver returned a row outside the plan it was given | the raw repo's select() ignored a predicate the framework scoped the read with — another tenant's row, a soft-deleted row, or another key — and the kit refused it before the caller saw it | evaluate every plan.where predicate in the driver's select(): selectRows(entity, rows, read) from @ultimat3/entity/adapter does it for an in-process store |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_DRIVER_UNSUPPORTED |
a custom driver was asked for a capability it does not declare | defineDriver({ capabilities }) omits the capability the call needs (meta.capability): transactions, lock, series, upsert, matches or aggregate: | implement the method on the raw repo and add its name to capabilities in defineDriver({ … }), or run that call on postgresDriver() |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_ALL_TRUNCATED |
.all() answered one page and dropped the cursor to the rest | a chain ending in .all() with no .limit(n) read its first 50 rows while more matched, so the caller holds neither every row nor a page it chose | x g guard repo-unbounded && x verify --only boundaries --json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_APPEND_ONLY |
an append-only entity was asked to rewrite or remove a row | the call would rewrite or remove a stored row, and the entity is declared appendOnly: true |
repo.insert(row) — append the correction as a new row, or remove appendOnly: true from the entity and run x db gen |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_COUNTS_INVALID |
references(…, { countedIn }) names no integer of its parent, or is no key to its primary key | a counter is an integer the database keeps on the parent, from a child key that references() that parent's primary key |
x db gen "count likes" after postId: uuid().references(() => posts.id, { countedIn: () => posts.likeCount }), with likeCount: integer().default(0) on posts |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_DUPLICATE |
two entities claim the same name | copy-pasted entity({ name })
|
rename one; x entities list --json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_OPERATOR_UNKNOWN |
a predicate names an operator outside the vocabulary | an operator that is not one of the closed set Operator declares — usually a SQL symbol ('>' for gt) or a different case ('GT'), reaching the plan through a cast, an operator built from a string, or a test run with no typecheck. Refused where the chain is written (andWhere) and again by both drivers for a plan built by hand, identically: before this the memory driver matched NO row with no error and the Postgres driver failed with a misleading X_SQL_UNSAFE. 500 — nothing the caller sends changes the answer, and the repair is an edit to source |
the fix opens with the call, the operator meant substituted — andWhere('likes', 'gt', value) # operators: eq, neq, … — and a placeholder with the whole list when nothing is close. SQL symbols map >→gt, >=→gte, <→lt, <=→lte, =→eq, !=/<>→neq; a known word in another case or with _ maps to itself ('GT', 'is_null'). The list is OPERATORS in @ultimat3/entity, and isOperator() tests a value read off the wire |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_PAGE_TOO_LARGE |
a page weighed more than the page byte bound before it was decoded | a read answered rows whose raw size passed MAX_PAGE_BYTES (64 MiB): every one of them would be decoded and held in memory at once | .select('id', 'title').limit(50) on the chain the refusal names — the columns the page renders, and fewer rows; inBatches(n) to visit every row |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_PARTITION_INVALID |
entity({ partitionBy }) declares a partitioning Postgres cannot build | the primary key or a unique index does not hold the partition column, the column is no timestamp() or date(), the interval is unknown, or retain/view/history sits beside it | entity('events', { primaryKey: ['id', 'at'], … }) // the member the cause names — then: x db gen "partition" |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_PREDICATE_NODE_INVALID |
a predicate tree (andWhereNode, a policy scope) no driver can answer | andWhereNode() was handed a tree no driver can answer: an unknown entity or column in a via hop, a sealed column, or more than 4 levels |
andWhereNode({ or: [{ column, op, value }] }) — or { via: { column, entity, target }, where: [ ... ] }, at most 4 levels deep |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_READ_ONLY |
a read-only entity was asked to write a row | entity({ readOnly: '' }) declares a table the app only reads — legacy history, a table another system owns — and its repository refuses every insert, update, upsert, delete and lock before any statement |
x entities show <entity> --json — the readOnly reason says why; write the table the app owns, or drop readOnly from entity('', { … }) when it is writable again
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_RETAIN_UNINDEXED |
entity({ retain }) names a column no index leads with | retain.on is a timestamp column with no index that starts with it, so every sweep would scan the whole table | entity('events', { indexes: [{ on: ['createdAt'] }], … }) // then: x db gen "retain index" |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_SEALED_IN_VIEW |
a sealed column is named in a view |
entity.$view([...]) lists a .sealed() column. A view is what leaves the server — an action's output, an OpenAPI schema, an MCP tool result — and a sealed column never does: $schema omits it for the same reason |
remove the sealed column from the $view([...]) list the cause names — server code reads it off the row; a caller that must be shown it gets its own field on a t.object output, set by the handler |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_SEALED_PREDICATE |
a sealed column is read by a predicate, an order or a rule the database evaluates | a .sealed() column in where, andWhere, orderBy, countBy, an aggregate, a filtered write's filter, an index or an invariant. The database holds ciphertext, so every comparison there is a comparison of ciphertexts: without lookup nothing matches, and with it only equality does — never an order, a range or like
|
edit the call the cause names — find the row by another column, or declare the column text().sealed({ lookup: true }) to allow equality (where / in / .unique()): equal plaintexts then store as visibly equal ciphertexts, so never for a low-entropy value |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_SERIES_INVALID |
a time series asked for something no bucket can answer | an unknown unit, an on column that is not a timestamp(), a zone that is not IANA, or more buckets than one statement answers | posts.series({ on: 'createdAt', unit: 'day', timeZone: 'Europe/Berlin', value: 'count' }) — a listed unit, a timestamp() column, an IANA zone, a range under the bucket ceiling |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
X_ENTITY_SERIES_UNSUPPORTED |
a repository has no series | db..series() was called on a hand-written Repo that does not implement it
|
Ultimate — v31.44.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