Skip to content

Error Codes db

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

Error codes: @ultimat3/db

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

Code Means Typical cause Fix
X_APPEND_ONLY_TRIGGER_MISSING an append-only table has lost its refusing trigger the table is declared appendOnly, and its trigger ultimate_append_only is missing or disabled bun run x -- db migrate --json — after running the two create statements the finding's own fix prints, against that database
X_BRANCH_EXISTS that branch database already exists two conditions, one code: x db branch create <name> for a name already taken — refused rather than overwritten, because a silent re-clone discards whatever the branch already held — or a dropBranch() aimed at the database this session is itself connected to, which Postgres cannot drop from underneath its own connection x db branch delete <name> # then re-create, or pick another name — x db branch list --json lists what exists. To drop the database you are connected to, point DATABASE_URL at the base database first, then x db branch delete <name> — never a raw drop database, which skips the branch-name check
X_DB_COMMIT_UNKNOWN the connection was lost while COMMIT was in flight the socket closed after COMMIT was sent and before the server answered, so the transaction is either durable or rolled back and this process cannot tell which; neither onCommit effects nor onRollback undos ran. Only the data can say which: a row the transaction wrote is present if it committed and absent if it did not psql "$DATABASE_URL" — a session on that database: select a row the transaction wrote, and re-run the unit of work only when it is absent
X_DB_DRAIN_TIMEOUT the pool did not drain inside its shutdown budget As of 2026-08-27: close() gave up waiting for a role's pool to hand its connections back. Bun.SQL's end() waits on an outstanding RESERVED connection and never stops — measured three runs per case on Bun 1.3.14 and 1.4.0, with the database perfectly healthy — so before PoolProfile.drainTimeoutMs a shutdown that met a pinned connection never finished, and the operator's only signal was a container that burned its whole termination grace period before SIGKILL. Raised on the elapsed time, because the driver RESOLVES when it gives up rather than rejecting: a drain that silently abandoned in-flight work looked exactly like a clean one. migrate and replicator are 0 and still wait forever, deliberately — a run-once role cutting off its own session mid-statement is worse than a slow exit psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'" finds the statement that will not finish — or raise drainTimeoutMs in postgresClient({ profile }) for the role cause names
X_DB_DRIFT schema differs from migrations a column exists in code but in no migration — or, on an app that declares an entity and has generated no migration yet, packages/db has a schema but no migration recorded it. An app declaring no entity is not drifting: zero declared against zero recorded is agreement. As of 2026-11-02 also the dump holds a column no migration's snapshot records (drift, no database): an applied migration was edited and regenerated into packages/db/schema/ x db gen "<describe the change>" then x db migrate; on a fresh scaffold that is x db gen "initial". A column no entity declares comes out of that as an empty diff: declare it, or restore the migration and x db reset. The dump case: git checkout -- packages/db/migrations packages/db/schema. The one difference this does not fix is unknown-schema — see X_MIGRATION_SNAPSHOT_MISSING below, whose two remedies it shares
X_DB_FOREIGN_KEY_VIOLATION a foreign key constraint rejected the row SQLSTATE 23503 — the parent row is absent, was deleted between the read and the write, or belongs to another tenant (a same-tenant key answers absent and foreign alike, and the memory driver refuses only the second). meta.constraint names the key insert the row the constraint cause names points at first, in the same withTransaction(...) — or drop the write, because the parent it names is gone or is not this tenant's
X_DB_LOCK_TIMEOUT the statement waited past its lock_timeout SQLSTATE 55P03 — usually a DDL statement queued behind a long transaction holding the same table, which then blocks every reader behind it. x db diagnostics --json | jq '.data.blockers.rows[] | {pid, blockedBy, blockerState}' — end the blockedBy session or wait for it, then re-run the statement
X_DB_POOLER_OPTIONS_REFUSED the connection pooler refused the libpq options a pool connects with the pooler answered 08P01 unsupported startup parameter at connection startup: a stock PgBouncer does not forward statement_timeout, so with DATABASE_POOLER unset every role fails on its first statement export DATABASE_POOLER=transaction && psql "<DATABASE_URL without its options parameter>" -c "alter role <user> set statement_timeout = '10s'" -c "alter role <user> set idle_in_transaction_session_timeout = '30s'" — session on a session pool; then reopen the pooler's server connections. A refused option of your own in DATABASE_URL's options: move it to alter role instead. Never psql "$DATABASE_URL": the pooler refuses those options again before alter role runs. The error's own fix: cuts the parameter with sed, so paste that
X_DB_POOLER_SESSION_REQUIRED this role needs one backend per session, and a transaction pooler gives it none ROLE=migrate or ROLE=replicator, or a step that applies a migration, under DATABASE_POOLER=transaction: session advisory locks and replication need one backend. Refused before a socket, because two migrators through a transaction pooler both read true from pg_try_advisory_lock unset DATABASE_POOLER for this role, and point its DATABASE_URL at the server's own port
X_DB_POOL_EXHAUSTED no connection was available SQLSTATE 53300 from the server, or the local pool answering nothing inside acquireTimeoutMs, for a plain statement as for a transaction (As of 2026-11-02) — deliberately one code, because to a caller both mean "there was no connection for this unit of work" and a second code would split one runbook in two. Refused rather than queued forever: a hang makes /readyz join the queue, the kubelet kills the pod, and the next pod inherits the same saturated database set DATABASE_POOL_MAX below max_connections / replicas (per-role default: POOL_PROFILES), or cut the replica count
X_DB_ROW_SECURITY_BYPASSED row security is on and the serving role is exempt from it database.rowSecurity is on and the connected role is a superuser, has bypassrls, or owns a tenant table whose row security is not forced — Postgres exempts all three, so the policy would refuse nothing psql "$DATABASE_URL" -c 'alter role <role> nosuperuser nobypassrls' # and serve as a role that owns no table: the migrator owns them, ROLE=migrate
X_DB_ROW_SECURITY_DRIFT a tenant table and database.rowSecurity disagree about its policy database.rowSecurity is on and a tenant table carries no forced tenant policy, or it is off and one still does — the migrations, the flag or the live database moved without the others x db gen "row security"
X_DB_SCHEMA_STALE the statement names a table or column the database does not have SQLSTATE 42P01 / 42703 — an entity edited before the migration that adds its column ran, on either driver (PGlite under x dev included). The cause leads with [SQLSTATE 42703] column "host_id" does not exist and carries the statement after it, excerpted, so the column list can never push the message off the line x db gen "<what changed>" && x db migrate — only the migrate half when the migration already exists
X_DB_SERIALIZATION_FAILURE the transaction lost a serialization race SQLSTATE 40001 or 40P01 — a serializable transaction whose read set another commit invalidated, or a deadlock the server broke. Retryable by definition, which is why it is its own code and not an outage withTransaction(fn, { retry: 3 }) — fn re-runs from the top, so it must be idempotent
X_DB_SIBLING_SCOPE_TIMEOUT a nested transaction scope waited too long for its sibling two withTransaction calls were started under one outer transaction and the first never finished inside siblingWaitMs — usually because its body awaits the second, which cannot start until the first returns await withTransaction(first); await withTransaction(second) — one after the other, never a nested body awaiting a sibling — or raise the wait: withTransaction(fn, { siblingWaitMs: 120000 })
X_DB_STATEMENT_BOUND_INVALID a statement bound is not a whole positive number of ms under the role bound withStatementTimeout(ms) or query({ timeoutMs }) asked for 0, a fraction, NaN, or more than the connected role statement_timeout — a read cannot extend what the role was sized for query({ timeoutMs: 500 }) # a whole number of ms below the role bound, read with: psql "$DATABASE_URL" -c 'show statement_timeout'
X_DB_STATEMENT_BOUND_LOST the session's statement bound is not the role's logged at boot and reported by x doctor, never a refusal: statement_timeout or idle_in_transaction_session_timeout as the session reads it differs from POOL_PROFILES, or is 0 with DATABASE_POOLER set. A pooler that ignores or drops libpq options does this silently psql "<DATABASE_URL without its options parameter>" -c "alter role <user> set statement_timeout = '10s'" -c "alter role <user> set idle_in_transaction_session_timeout = '30s'", then reopen the pooler's server connections; or export DATABASE_POOLER=transaction if a pooler sits in the path. The error's own fix: cuts the parameter with sed
X_DB_STATEMENT_FAILED the database refused the statement any SQLSTATE the table does not classify — a syntax error, a data exception, a check or not-null violation. The server's verdict, so re-running it gives the same verdict, and the connection is not the problem. 25P03 is the exception to that reading: the server closed a transaction idle past idleInTransactionMs, and its fix is to do slow outbound work before opening the transaction read the SQLSTATE and message in the cause; psql "$DATABASE_URL" -c "<the statement>" reproduces it by hand
X_DB_STATEMENT_TIMEOUT the statement ran past its statement_timeout SQLSTATE 57014 — a sequential scan where an index was assumed, or a plan that changed under a grown table. On the memory driver, a lock or lockKey waiter past 5 s: usually two locks taken in opposite order add the index this statement needs to the entity (indexes: [...]), then x db gen "add index"
X_DB_TRANSACTION_ABORTED the server rolled the transaction back a statement failed inside withTransaction and the body caught it instead of rethrowing; Postgres aborts the whole transaction on any statement error, so COMMIT answers ROLLBACK and nothing is stored await withTransaction(() => fallible()).catch(fallback) — a nested scope is a SAVEPOINT: only it rolls back — or rethrow the statement error
X_DB_TRANSACTION_CLOSED statement on a finished transaction a statement was sent on a transaction handle whose scope had already committed or rolled back: an un-awaited promise, or the loser of a Promise.all, outlived withTransaction await it inside withTransaction(fn); for work that must outlive the scope, wrap it in outsideTransaction(fn)
X_DB_UNAVAILABLE cannot reach the database nothing listening on DATABASE_URL, a closed pool, or @electric-sql/pglite not installed for a pglite:// url — every failure that never reached a server, and As of 2026-09-05 only those: a failure carrying a SQLSTATE is proof the server answered and is one of the two rows below. The driver's own words ride in the cause (ECONNREFUSED 127.0.0.1:5432). As of 2026-11-02 also a plain statement with no answer past the role's statement timeout + 5 s: the cause names the bound and the statement, the pool is replaced and the next statement opens a new one, and an autocommit write may have landed. Unclassified for retry, so a job worker re-runs the attempt: that write runs again, at least once DATABASE_URL=postgres://user@host:5432/database — a reachable Postgres — or x dev for the embedded PGlite; bun add @electric-sql/pglite when the url is pglite://
X_DB_UNIQUE_VIOLATION a unique constraint rejected the row SQLSTATE 23505 — two clicks racing a signup, or an insert where an upsert was meant. One of six driver failures that used to reach the caller as X_DB_UNAVAILABLE, whose fix reads "set DATABASE_URL to a reachable Postgres": a raced signup paged on-call for an outage that never happened. meta.constraint names the index the server refused on upsertAll(rows, { onConflict: [...] }) over the columns the constraint cause names — or catch X_DB_UNIQUE_VIOLATION and answer 409, which is what a raced signup is
X_ENTITY_RETAIN_INVALID entity({ retain }) has no window, sits beside appendOnly, or is on a partitioned table retain needs an after window the app chose; appendOnly refuses every delete; a partitioned table is retained by detaching partitions entity('<name>', { retain: { after: '90d', on: 'createdAt' } }) — set after, drop appendOnly or retain, or detach old partitions in a task; then x db gen "retention"
X_KEYSET_NULL_KEY a keyset page holds a null in one of its sort keys a raw read paged with keyset() met a null in a key not declared nullable: true — a row comparison has no null order, so the null rows would fall off every page — or the final tiebreak key is declared nullable, which keyset() refuses before any row is read: rows null on it tie with no order between them keyset({ keys: [{ column: raw('p.published_at'), kind: 'timestamptz', direction: 'desc', nullable: true }, { column: raw('p.id'), kind: 'uuid', direction: 'desc' }], … }) # declare the key nullable; the last key stays not null
X_LIFECYCLE_TRIGGER_MISSING a history or counter trigger the migrations created is missing from the database someone dropped or disabled ultimate_history, ultimate_history_guard or an ultimate_count_* trigger, so writes no longer record history or keep counts x db migrate --json — the finding names the psql statement that re-creates the trigger; then x db recount . --write for a counter
X_MIGRATE_CONCURRENT another migrator holds the migration lock two overlapping deploys, or a migrator wedged on a partition — or OOM-killed with its backend still alive — still holding pg_advisory_lock(<key>) when the wait ran out. pg_advisory_lock blocks with no timeout, so that case left helm upgrade --wait sitting inside one statement, printing nothing, with the job never failing so backoffLimit never fired. As of 2026-08 a bounded pg_try_advisory_lock poll turns it into an exit code psql "$DATABASE_URL" -c "select pid, application_name, state from pg_stat_activity join pg_locks using (pid) where locktype = 'advisory'" — pg_terminate_backend(pid) the wedged migrator, then x db migrate
X_MIGRATION_APPEND_ONLY_BACKFILL a NOT NULL column added to an append-only table needs a default existing rows could only get a value by an UPDATE the append-only trigger refuses entity('<name>', { columns: { <col>: <builder>.default(<value>) } }) — then re-run x db gen
X_MIGRATION_CONCURRENT_IN_TRANSACTION a concurrent index statement is in a migration that runs inside a transaction a hand-written migration holds create index concurrently, drop index concurrently or reindex … concurrently but no -- transaction: false line, and Postgres refuses all three inside a transaction block (25001). Refused before the transaction opens, so nothing is applied sed -i '1i -- transaction: false' packages/db/migrations/<id>.sql — before it is applied — or move the statement into a migration of its own
X_MIGRATION_CONCURRENT_PARTITIONED a concurrent index build names a partitioned table Postgres builds no index concurrently on a partitioned parent (SQLSTATE 0A000); a migration ran create index concurrently on one CREATE INDEX CONCURRENTLY <index>_<partition> ON <partition> (<columns>); per partition, then CREATE INDEX <index> ON ONLY <parent> (<columns>);, then per partition ALTER INDEX <index> ATTACH PARTITION <index>_<partition>; — in a -- transaction: false migration (Partitioned tables)
X_MIGRATION_CONFLICT the migration ledger disagrees with this build a ledger row from an app version this build does not ship, an applied migration whose file was edited so its checksum moved, or a rollback aimed at a row whose down SQL exists only in the build that shipped it. x db status --json (As of 2026-11-15) lists what disagrees without taking the migrate lock: data.ahead, ledger rows this build does not ship, and data.edited, applied migrations whose file now hashes otherwise. One narrow exception is not a conflict (As of 2026-10-05): when every unknown ledger row sorts after the newest migration the build ships, and the build has no migration left to apply, the migrator reads it as a rollback onto a newer build's schema — it applies nothing, logs ultimate migrate ledger ahead of build and returns the ids as ahead. Every other rollback state is still X_MIGRATION_CONFLICT: an unknown row between shipped migrations, a shipped migration this database never applied, or a build that ships no migrations at all the fix branches on which half disagreed. Foreign ledger row: deploy the app version cause names, or drop its row — psql "$DATABASE_URL" -c "delete from x_migrations where id = '<id>'". Moved checksum: git log -- packages/db/migrations/<id>.sql, then git checkout <rev> -- … the revision whose checksum the ledger names (a committed edit is what HEAD holds), never edit an applied migration, then x db gen "<change>". x db gen alone exits 0 and writes the edit into the schema dump. Unknown down: x db status --json, or on a box with no CLI read the ledger with psql "$DATABASE_URL" -c "select id, app_version from x_migrations order by id desc limit 5" and roll back on the build that shipped it
X_MIGRATION_DESTRUCTIVE this migration destroys data and does not say so As of 2026-08: a committed migration whose up drops a table, drops a column, truncates or retypes, with no -- destructive: true line in the file. Raised by x verify's drift step over the files, never by the migrator — the rail fails in CI, before a release phase applies it. Only up is judged: reversing a create table is a drop table, and marking every down marks nothing x db gen "<name>" --allow-destructive to regenerate it — the generator writes the marker itself — or add the line -- destructive: true to the migration. Add it before the migration is applied: the marker is SQL the checksum covers, so marking an applied file is an edit and answers X_MIGRATION_CONFLICT
X_MIGRATION_IRREVERSIBLE this migration cannot be reversed without data loss a generated plan that drops a column or a table x db gen "<name>" --allow-destructive, or put the column back in columns and keep it
X_MIGRATION_LOCK_HEAVY this migration holds a live table still for a full scan a committed migration newer than the rail (LOCK_HEAVY_SINCE) runs set not null with no validated check before it, or create index without concurrently, on a table it did not create: Postgres scans every row under a lock that stops writes (ACCESS EXCLUSIVE, or SHARE for the build). Raised by the drift step over the files alter table "<t>" add constraint "<t>_<c>_not_null" check ("<c>" is not null) not valid; # deploy, then a new migration: alter table "<t>" validate constraint "<t>_<c>_not_null"; alter table "<t>" alter column "<c>" set not null; alter table "<t>" drop constraint "<t>_<c>_not_null"; — for an index: create index concurrently … on "<t>" (…); in a migration of its own whose first line is -- transaction: false. A deliberate one: add the line -- lock-heavy: true directly above that statement in the migration's .sql file before x db migrate applies it
X_MIGRATION_PARTITION_CHANGE an existing table gained or lost entity({ partitionBy }) Postgres cannot partition a table in place, nor turn a partitioned one back into a plain table: both are a new table and a copy of every row put partitionBy back as the table was created, or declare a new entity with partitionBy, backfill() its rows from the old one, then drop the old one in a later release (wiki/Migrations-And-Backfills.md#partitioned-tables)
X_MIGRATION_ROLLBACK_DESTRUCTIVE a rollback would serve an older build over a destructive migration the ledger holds a migration a newer build applied that drops or rewrites data (isDestructiveMigration), and the build starting now predates it x deploy --image <the newer image> --json — roll forward; or, after checking this build runs on the newer schema, set ROLLBACK_ALLOW_DESTRUCTIVE= on the migrate role
X_MIGRATION_ROLLING_UNSAFE this drop or rename would break the pods still running the old release during a rolling deploy the old release keeps reading every column it declares, so a column dropped or renamed in the same release answers X_DB_SCHEMA_STALE on every read and insert of the old pods. Raised by x db gen for a drop not retired first, by the drift step (bounded by rollingSince in x.verify.json) over a committed migration, and by migrate() in production when a retire and its contract are both pending entity('<t>', { retired: ['<c>'] }), then x db gen "retire <c>", deploy, then remove it from retired and x db gen "drop <c>" --allow-destructive; one instance that stops before the next starts: x db gen "<name>" --allow-destructive --rolling-unsafe
X_MIGRATION_SNAPSHOT_MISSING the newest migration records no schema snapshot As of 2026-08: x db gen found the newest migration on disk carrying no <id>.snapshot.json sidecar — deleted, or hand-written without one. Every generated migration writes the sidecar the next generation diffs against, so there is nothing to diff the entities against. Refused rather than defaulted to the empty schema, which would emit create table for every table the database already holds. A scaffold no longer starts in this state: x new writes no migration at all, and x db gen is the one writer of that directory. x doctor reports it too, As of 2026-08, so the condition is visible before a generate hits it git checkout -- packages/db/migrations/<id>.snapshot.json, or, when it was never written, delete the whole migration first and regenerate: rm packages/db/migrations/<id>.* && x db gen "<name>". That order is the fix — naming x db gen while the file is still there re-raises this code. The same condition reaches x db migrate as X_DB_DRIFT with an unknown-schema difference, whose fix: names the same two remedies in the same order
X_MIGRATION_VIEW_DEPENDS a view is compiled against a column this migration retypes As of 2026-08-25: a preflight, run inside each migration's own transaction before its first statement, in both x db migrate and x db rollback. A view stores a compiled parse tree, not its text, so alter table … alter column … type under a dependent view is 0A000 cannot alter type of a column used by a view or rule and rolls the WHOLE migration back. The generator cannot see this by construction — a view is on no SchemaDescription, introspect() excludes views, and no entity can declare one — so the check lives where a connection exists. Until this code, the failure reached an operator as X_DB_UNAVAILABLE: cannot reach the database on a database the migrator was mid-transaction on, with the server's own rule _RETURN on view … depends on column sitting unread in a DETAIL field cause names the view, the table and the column; fix is a runnable pair of psql "$DATABASE_URL" -c '…' invocations — drop the view, then x db migrate, then re-create it from the create view the fix line carries verbatim, read out of pg_get_viewdef before the drop. Single-quoted deliberately: identifier() writes the view name in DOUBLE quotes, so the -c "…" form the sibling migration errors use would end the shell word at the name. A view whose name identifier() refuses (a quote, a space, a backslash — all legal inside a quoted Postgres name) gets a fix that names the view as JSON and asks you to quote it, rather than a fix: that throws
X_SCHEMA_DUMP_DRIFT the committed schema dump is not what the migrations produce a file under packages/db/schema/ was edited by hand, a migration was written or changed without regenerating the dump, or the dump was never generated. The cause names the first file that differs; a dump that does not load back into the schema it was rendered from reports here too x db gen
X_SQL_UNSAFE SQL was built by string interpolation a non-scalar interpolated into a sql template, or an identifier or branch name that is not [a-z0-9_-]+ sql`… ${scalar} …` — a scalar binds as $n; a nested sql fragment composes; wrap audited SQL in raw(). cause numbers the interpolation

Clone this wiki locally