Skip to content

Error Codes entity

github-actions[bot] edited this page Nov 16, 2026 · 2 revisions

Error codes: @ultimat3/entity

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
database(entities, { driver: postgresDriver() }) — the shipped drivers both answer series; a hand-written Repo implements it
X_ENTITY_STALE the row's version moved since this write read it an update named the declared version (entity({ version })) it read, and another write landed first: the conditioned statement matched no row at that version. 409 and not 422: the identical request succeeds after a re-read const fresh = await db.notes.findById(id) — re-read, re-apply the change, send fresh.lockVersion back with the patch
X_ENTITY_TENANT_UNDECLARED a child of a tenant-owned table has no tenant an entity with no tenant column references, directly or through other entities, an entity that has one, and declares no shared reason, so a row of one tenant is readable by id from another add orgId: uuid().tenant() to the entity, then x db gen '<table> tenant'; or declare shared: '<why it belongs to no tenant>'
X_ENTITY_VERSION_INVALID a write or declaration breaks the declared version lock entity({ version }) names a column that is not a NOT NULL integer with a default, or update/updateMany omitted the version, a filtered write tried to set it, or upsertAll would overwrite rows it never read db.notes.update(id, { ...patch, lockVersion: row.lockVersion }) — carry the version read; filtered writes put it in where(), upsertAll uses onMatch: 'nothing'
X_ENTITY_VIEW_READ_ONLY a view entity was asked to write a row insert, update, upsert or delete reached an entity declared with view: { sql }, which is a relation Postgres derives and no row can be written to db.<source>.insert(row) — write the table the view reads; the view answers it on the next read (materialized: after refreshView runs)
X_INVARIANT_VIOLATED a domain invariant rejected this row a CHECK or a declared invariant failed. This page printed x entity explain until 1.2.0; the registry command is plural and its subcommands are list and show x entities show <entity> --json — every invariant with its kind, message, sql and where
X_LOCK_UNSUPPORTED a repository has no lock db..lock or lockKey was called on a hand-written Repo that does not implement it
implement lock and lockKey on the driver, or use the shipped postgresDriver()
X_NOT_FOUND no row for that id stale id, wrong tenant, or already deleted — or a single: true query's GET /_x/query/<name> whose sql matched no row (404; fix: x queries show <name> --json) confirm with psql "$DATABASE_URL" -c "select id from <table> limit 5" — x db has no query subcommand
X_N_PLUS_ONE_QUERY a read repeated once per row one lookup per row of a page — members.findById fifty times where one in statement would answer. Counted per request by the statement ledger x dev installs, and never counted in production. Reported on four surfaces at once: x dev's findings, /_x/timeline's nPlusOne, the browser overlay under the error, and one logger.warn per request per code. Thrown in one place only — a test that destructures @ultimat3/testing's statements fixture, where the loop's fifth statement rejects and fails the test the fix is the preload the schema already declares, e.g. db.posts.preload('author'). No relation points at the entity ⇒ the batched form of the same read, db.members.andWhere('id', 'in', ids).all(). A loop that is genuinely one statement per row is declared, not silenced: expectedQueryLoop('<why>', fn)
X_N_PLUS_ONE_WRITE a write repeated once per row one insert, update or delete per row of a set, where one statement writes all of them. Same four surfaces as the read above, same ledger, and the same throw inside the statements fixture the bulk form of the same call: db.posts.insertAll(rows), db.posts.updateWhere(filter, patch), db.posts.deleteWhere(filter) — or expectedQueryLoop('<why>', fn) when the loop is deliberate
X_PATCH_EMPTY updateWhere(), a chain's updateAll() or updateMany() named no columns to write an empty patch, or one whose only value came back undefined — reporting "n rows updated" for a statement that set nothing is the silent no-op the count exists to prevent name the columns to write, e.g. db.participants.updateWhere({ conversationId, userId }, { lastReadAt }) or db.participants.where(filter).updateAll({ lastReadAt })
X_PRELOAD_UNKNOWN_RELATION no relation of that name on this entity a typo, or a relation the schema never declared — relations are derived from references() columns, so there is no list to read them off the fix is a call on one that exists, e.g. relationNamed('posts', 'author') # or: org, likes. No foreign key at all ⇒ x entities list --json, then add .references(() => <target>.id) to the column that points at one
X_RECORD_KEY_MISSING a row reached its record key without a primary-key value an entity row reached the client-record path, either rowsOf building the record envelope or recordProjection(e).key, and one of its primary-key columns was missing or not a string, number, bigint, boolean or valid Date. A handler built the row by hand, or handed a partial row where the output schema declared the entity's row. Refused rather than keyed as undefined, because two keyless rows would be one record x entities show <entity> --json lists the primary key. Return the whole row (every primary-key column) from the handler that built this one
X_REPO_CLIENT_PINNED a repository pinned to its own client cannot join the open transaction a repository built through postgresDriver({ client }) used inside a transaction that was opened on another client. Refused rather than resolved: the pinned client takes a different connection out of its pool, so the write commits immediately and survives the rollback while the read cannot see rows the transaction already wrote — both silently. A transaction opened on the pinned client (withTransaction(fn, { client }), driver.transactor()) is joined, As of 2026-10-02 — tx.origin says it is the same database setDbClient(client) at boot and build the repository with no client: — postgresDriver() then resolves the open transaction through db() — or run this call outside withTransaction()
X_SEARCH_IN_MEMORY the in-memory driver cannot answer a full-text match a search run against memoryDriver(). REFUSED rather than emulated, and that is the whole decision: to_tsvector stems, drops stop words and applies a language's own rules, and websearch_to_tsquery parses quoted phrases and -negation — a JS token comparison is a DIFFERENT question with the same shape, so it would answer green in a unit test and differently in production, which is the one outcome the two-driver split exists to prevent. 500 for the same reason as the row above move this read into a <name>.live.test.ts and run it with TEST_DATABASE_URL set — bun test packages/entity/src/pg-search.live.test.ts is the model
X_SEARCH_UNDECLARED this entity has no searchable column a matches predicate on an entity whose columns declare no .searchable(), so there is no tsvector to match against. Raised where the STATEMENT would be built and not where the chain was written, because both drivers reach it: a search vector is derived from the entity's own columns, so there is nothing else the predicate could name and no vector to guess at. 500 and not a 4xx — nothing the caller sends changes the answer, and the repair is an edit to the entity add .searchable() to a text() column of <entity>, then: x db gen "search <entity>"
X_STATE_CONFLICT the row changed after the read this transition was decided on the lost update, caught: two callers both read pending, both found the move legal, and the second one's statement carried status = 'pending' in its predicate and matched nothing. Or the row is still in from but a column the deciding policy read (move.observed, #702) changed — cause names the column, never its value. The state in cause is read back AFTER the refusal, so it is a diagnosis and never the decision — the decision was the statement, and it was atomic. 409 and not 422: nothing is wrong with the request, the identical one succeeds a moment later, and re-read-and-retry is precisely what a 409 tells a client to do re-read the row and decide again against the state cause names: orders.findById(id) — a transition names the state it expects, so a stale read is refused rather than overwritten
X_STATE_TRANSITION_ILLEGAL the machine has no such transition three conditions and one code, because they share one repair — the move is not in the table — and cause states which. "<from>" is not a state the enumerated() set declares; the row is terminal in "<from>", an empty move list being how a terminal state is written; or the move to "<to>" was never declared. The unknown-state branch is separate because an unknown state has no outgoing moves either, so a single "no legal moves" answer reported a typo as "the row is terminal in <typo>" — a sentence about a state that does not exist. 422 and not 400: the request is well formed and its schema passed, which is X_INVARIANT_VIOLATED's shape and takes its status. Refused before any statement opens a connection, so nothing was written the fix is the same call with a legal target substituted — orders.transition('status', id, { from: 'pending', to: 'paid' }) — or add "<to>" to the "<from>" entry of the transitions() table
X_STATE_UNDECLARED that column declares no state machine transition() on a column with no .transitions() — a declaration bug and not a caller's, which is why cause lists the columns that DO declare one: the repair is naming a different column or writing the table, and both are edits to source. 500, the same shelf as X_SEARCH_UNDECLARED add .transitions(…) to <entity>.<column> — it must be an enumerated() column, and every value that set declares needs an entry. When other columns already declare a machine, the fix lists those instead
X_TENANCY_ACTOR_MISMATCH a call named a tenant other than the actor's — as a query predicate, or as the tenant column of a row being written an orgId that arrived as action input, a query string or a path parameter, passed into a repo call; or an insert/upsertAll row, or an update patch, naming another tenant — the cause names both tenants drop the orgId argument, the actor's tenant scopes the plan; or act as that tenant with withChildContext({ actor }); a read that must span tenants is crossTenant('<why>', fn)
X_TENANCY_ACTOR_ORG_REQUIRED the acting actor carries no tenant anonymous, or a service actor minted without an orgId, reading a tenant-scoped entity mint the actor with its tenant at the request boundary — userActor({ id, orgId }) — or crossTenant('<why>', fn)
X_TENANCY_CROSS_DENIED a cross-tenant read was entered without the capability crossTenant() called by an actor lacking tenancy:cross, or outside every request context — the capability is re-checked on every plan built inside the scope, so an actor swapped in by withChildContext() does not inherit the reach mint the actor with the scope — serviceActor({ id: 'reconciler', scopes: ['tenancy:cross'] }) — run inside runWithContext(ctxOf({ actor }), fn), and wrap the reads in crossTenant('<why this spans tenants>', fn); the reason is required and non-blank, because it is what the next reader greps for
X_TENANCY_UNSCOPED a tenant-scoped query has no org predicate a repo call outside any request context, so there is no actor to derive the tenant from; a plan handed to the verify-only assertScoped() while an actor is present; or an upsertAll(rows, { onMatch: 'update' }) whose onConflict omits the tenant column — a collision there lands on another tenant's row the cause says which of the two it is. No context: runWithContext(ctxOf({ actor }), fn) from the script or seed. Actor present: build the plan through scopedPlan(), or orgScoped(plan, ctx.actor.orgId). For the upsert: put the tenant column in onConflict
X_TEST_DRIVER_CLIENT_CHANGED The installed client changed inside a testDriver() transaction setDbClient installed or cleared a client while a transaction opened through testDriver() was still running, so its writes would land in two stores beforeAll(() => setDbClient(client)); afterAll(() => setDbClient(undefined)); # outside every transactor().run / withTransaction scope
X_WRITE_UNFILTERED deleteWhere(), updateWhere() or a chain's updateAll()/deleteAll() named no filter an empty filter, one whose only value came back undefined, or a chain predicate holding undefined — the two look identical at the call site, and either would reach every row name the columns that bound it, e.g. db.likes.deleteWhere({ postId, userId }) or db.likes.where({ postId, userId }).deleteAll(). A deliberate whole-table write is a migration: x db gen "<name>"

Clone this wiki locally