Error Codes
ScramDB speaks the PostgreSQL wire protocol and PostgreSQL's own SQLSTATE codes, so most of a client's cluster error handling is code it already has. The whole cluster failure surface is four SQLSTATEs, produced by one function in the engine, plus one connection-level case that carries no SQLSTATE at all because no server ever got the chance to send one. 40001 is the same serialization_failure every PostgreSQL driver and ORM already retries; clustering just adds new reasons the cluster can raise it. 57P01 and 57P03 are PostgreSQL's own admin_shutdown and cannot_connect_now, both plain reconnect cases. The one genuinely new thing a distributed engine has to hand a client is 08007: an outcome that is honestly unresolved rather than known-good or known-bad. This page exists mainly to make that one case impossible to get wrong.
One place in the engine owns this entire mapping. Every cluster-shaped failure is matched there explicitly; a new failure variant does not compile until it has a contracted code, and nothing cluster-shaped falls through to a generic internal error. Read the table below once and a retry loop built from it needs no other input.
The master table
| SQLSTATE | PostgreSQL name | Retry class | What actually happened | What the client must do |
|---|---|---|---|---|
40001 | serialization_failure | Definite | The transaction left no effect anywhere in the cluster. | Re-execute the transaction. Safe unconditionally. |
08007 | transaction_resolution_unknown | InDoubt | The write was accepted and may still commit; its outcome was never observed. | Reconnect, verify whether it applied, and retry only if the statement is idempotent. |
57P01 | admin_shutdown | Unavailable | This node is draining or shutting down; the statement never reached the cluster. | Reconnect to a different node. |
57P03 | cannot_connect_now | Unavailable | The cluster has not finished forming yet, a cluster table's shard assignment has not reached this node yet, or this node's copy could not catch up in time for a read; the statement never reached it, or read nothing. | Back off and reconnect. |
| (none) | driver-level connection error before COMMIT was sent | Unavailable, handled like 57P01 | The connection died before any server could answer, and the transaction had not asked to commit. Nothing was decided. | Reconnect to a different node and re-execute. |
| (none) | driver-level connection error after COMMIT (or an autocommit write) was sent | InDoubt, handled like 08007 | The connection died after the commit was asked for; the commit may have happened. | Reconnect, verify whether it applied, and retry only if the statement is idempotent. |
40P01 | deadlock_detected | Definite | Two or more transactions on different nodes each waited on a lock the other held. ScramDB detected the cycle cluster-wide and aborted one of them; the aborted transaction left no effect. | Re-execute the aborted transaction. |
42704 | undefined_object | not a cluster failure | SET, SHOW or RESET named a configuration parameter that does not exist. | Fix the parameter name. Retrying will not help. |
55P02 | cant_change_runtime_param | not a cluster failure | A setting was changed where its context does not allow it: a setting fixed at server start, a setting only the server configuration sets, or one a session may not change now. | Change it in the configuration file, or restart the server. |
54001 | statement_too_complex | not a cluster failure | A statement's own expression tree nests deeper than can be safely evaluated, or a function, procedure or trigger recurses too deeply. | Rewrite the statement or the routine to nest shallower. Retrying unchanged will not help. |
22003 | numeric_value_out_of_range | not a cluster failure | An arithmetic result does not fit its type: an integer, bigint or smallint out of range, a floating-point overflow, a NUMERIC result past PostgreSQL's own bounds, or a SUM or AVG of NUMERIC whose total passes 38 significant digits. | Fix the query or the data. Retrying unchanged will not help. |
57014 | query_canceled | not a cluster failure | The statement was cancelled: statement_timeout elapsed, or a client sent PostgreSQL's CancelRequest or called pg_cancel_backend(). | The session is still usable. Re-issue the statement if it should still run. |
42883 | undefined_function | not a cluster failure | LIKE or ILIKE was used against an operand that is not text, such as an integer or an enum column. | Cast the operand to text first. Retrying unchanged will not help. |
53100 | disk_full | not a cluster failure | A write had no room to land: the storage device is full. The statement changed nothing. | Free space on the storage device, then re-execute the statement. |
428C9 | generated_always | not a cluster failure | A statement wrote a value other than DEFAULT to a generated column or to a GENERATED ALWAYS identity column. The statement changed nothing and drew no sequence value. | Leave the column out, write DEFAULT, or for an identity column use OVERRIDING SYSTEM VALUE on INSERT. Retrying unchanged will not help. |
42P18 | indeterminate_datatype | not a cluster failure | An ARRAY[] constructor with no elements and no cast has no type of its own, whatever the target column's type is. | Add an explicit cast, for example ARRAY[]::integer[]. Retrying unchanged will not help. |
42P01 | undefined_table | not a cluster failure | A column reference named a table or alias that no relation of the statement answers to (SELECT "T".a FROM ct t, or ct.a after the table was given an alias). Identifiers fold as in PostgreSQL: an unquoted name folds to lower case and a quoted one keeps its spelling. The statement changed nothing. | Qualify with the alias or table name as it was written in the FROM clause. Retrying unchanged will not help. |
42712 | duplicate_alias | not a cluster failure | Two relations of one FROM or USING list carry the same name after folding (FROM cu s, cu S), so a qualified reference could not tell them apart. The statement changed nothing. | Give one of them another alias. Retrying unchanged will not help. |
25001 | active_sql_transaction | not a cluster failure | A statement that commits as it goes (REINDEX of a partitioned table or index, REINDEX CONCURRENTLY, SCHEMA, DATABASE, SYSTEM, CLUSTER with no table or of a partitioned table, ALTER SYSTEM) ran where a ROLLBACK could not undo it: in a transaction block, after a SAVEPOINT, in a message of several statements, or from a function. It did nothing. | Run it as a statement of its own outside a block and outside a function. |
2202E | array_subscript_error | not a cluster failure | An array that cannot take the shape asked of it: the sub-arrays of a multi-dimensional constructor differ in size, array_cat or array_agg meets arrays whose dimensions do not fit, a store reaches outside a multi-dimensional array, or a trim_array count is out of range. The statement changed nothing. | Make the dimensions agree. Retrying unchanged will not help. |
54000 | program_limit_exceeded | not a cluster failure | An array of more than six dimensions or more than 134,217,727 elements, or an array bound past the integer range. The statement changed nothing. | Use fewer dimensions or split the array. Retrying unchanged will not help. |
22P03 | invalid_binary_representation | not a cluster failure | A binary array (a bind parameter or COPY ... (FORMAT binary)) whose flag word, element lengths or trailing bytes are not PostgreSQL's array form. The statement changed nothing. | Fix the client's binary encoding of the array. Retrying unchanged will not help. |
22007 | invalid_datetime_format | not a cluster failure | A text read as a DATE, TIME, TIMESTAMP or TIMESTAMPTZ is not in any form PostgreSQL reads (invalid input syntax for type date: "..."). | Fix the text, or write it in ISO order. |
22008 | datetime_field_overflow | not a cluster failure | A date or time text names a field out of range (date/time field value out of range). When the text is valid under another DateStyle order the message carries the HINT Perhaps you need a different "DateStyle" setting. | Fix the value, or SET DateStyle to the order the text uses. |
22009 | invalid_time_zone_displacement_value | not a cluster failure | A numeric time zone offset in a date or time text is out of range. | Write an offset within a day. |
57P05 | idle_session_timeout | not a cluster failure | A session sat idle outside a transaction for longer than idle_session_timeout; the server closed the connection. | Reconnect, or raise the timeout for the session with SET idle_session_timeout. |
25P03 | idle_in_transaction_session_timeout | not a cluster failure | A session sat idle inside a transaction for longer than idle_in_transaction_session_timeout; the transaction was rolled back and the connection closed. | Reconnect and run the transaction again. |
58030 | io_error | not a cluster failure | A file the statement read or wrote failed at the operating system, a spill file could not be started, or the server's log is failed and refuses writes. The statement changed nothing. | Check the data volume and the temporary directory, then re-execute the statement. While the log is failed, reads go on and writes go through again once the log heals; see below. |
XX001 | data_corrupted | not a cluster failure | The record of a prepared transaction is damaged or missing. | Only ROLLBACK PREPARED resolves it; then run the transaction again. |
Three retry classes cover the whole table:
- Definite: the transaction provably left no effect. A blind re-execute is unconditionally safe, exactly what PostgreSQL's own
40001already trains every ORM to do. - InDoubt: the write may still commit. It was accepted somewhere and its outcome was never confirmed, so re-executing blindly risks applying it twice.
- Unavailable: the statement never entered the cluster at all. Nothing is in doubt because nothing was ever attempted; the right move is to reconnect, possibly elsewhere, rather than retry in place.
How the contract holds together
One function, no exceptions
Every cluster-shaped failure the engine's driver layer can produce is classified by one function. It matches each failure case explicitly: add a new one and the match stops compiling until it is given a contracted code. That is deliberate, and it is the only mechanism that keeps a cluster failure from reaching the generic XX000 internal-error fallback or getting a SQLSTATE invented for it at the call site that happened to hit it.
The engine holds itself to the same rule internally. Its own bounded internal retries, for instance a bulk COPY riding out a leader election mid-load, only ever fire for a Definite failure, never for an in-doubt one; retrying an in-doubt failure inside the engine would double-apply exactly as a client's blind retry would.
InDoubt and Definite are never merged, and no code path collapses one into the other. 40001 means the transaction provably left no effect: re-executing it is always safe. 08007 means the opposite is possible: the write was accepted and may already have committed. Treating an in-doubt outcome as a definite one and blindly retrying is exactly how a non-idempotent write gets applied twice. This is the one distinction on this page that actually matters; the rest is bookkeeping.
Do not parse the message to decide whether to retry
The message text always names the real cause, even when several causes share one SQLSTATE, so a log line still tells a human whether a given 40001 was a write conflict, an election, or a stale schema epoch. It is not, however, a stable API: retry logic should switch on the SQLSTATE alone.
Where the hint text actually is
Every cluster failure carries a one-sentence hint alongside its message ("re-execute it", "reconnect and verify", and so on). On the wire that hint is not a separate structured field: it arrives appended to the message text itself, as a trailing HINT: <text> line under the same SQLSTATE. A client that only reads the raw message string still gets the hint; there is nowhere else to look for it.
A coded error keeps its SQLSTATE through COMMIT
An error raised while a COMMIT is being sent still carries its original SQLSTATE, wrapped in a COMMIT failed: ... message, rather than losing its code and arriving as a generic failure. PREPARE TRANSACTION and COMMIT PREPARED keep their own error's SQLSTATE the same way, without that added wrapper text. A client that switches on the SQLSTATE alone, per the rule above, sees the same code whichever of the three failed.
SQLSTATE 40001: serialization_failure
Hint, fixed for every cause below except the last two: the transaction left no effect; re-execute it
Every one of these is Definite: whatever happened, it happened before anything committed, so re-executing the transaction from the start is always correct. The contract folds eight distinct causes into this one code; the message always says which one it was.
| Cause | Message shape |
|---|---|
| The commit lost to a transaction it conflicted with: another transaction committed a change to a row this one wrote or read, or the two committed at the same moment and this one, the younger, gave way | could not serialize access due to concurrent update |
| A row the transaction read was changed by another transaction's commit before this one's commit could be decided | could not serialize access due to read/write dependencies among transactions |
| A table the transaction wrote or read changed its placement while the transaction ran | the table's placement changed while the transaction ran; retry the transaction |
| The cluster lost the transaction's commit state before its commit was decided | the transaction's commit state was lost before any vote; retry the transaction |
| A read position could not be chosen because a shard group has no leader | the snapshot could not be taken because a shard group has no leader ({detail}); retry |
| A statement names a table whose schema change the cluster decided and this node has not applied within the statement's wait | table "{name}" is not up to date on this node yet |
| Stale schema epoch (the statement planned against a superseded catalog) | schema changed while this statement was planning ({detail}); re-execute so it re-plans against the current catalog |
A learner_read = stale read whose replica has fallen behind max_staleness, or whose lag cannot be measured yet | bounded-staleness read refused: group {group} is {age}ms behind, past the {bound}ms staleness bound, or bounded-staleness read refused: replica lag is not measurable yet (nothing applied on a required group) |
{detail} is filled in with the specifics of what actually happened. None of that changes the SQLSTATE, only the message. The staleness-bound row carries its own hint instead of the fixed one above: retry, or use learner_read = 'strong'. The not-up-to-date row carries Retry the statement in a moment.: a change of the table's definition has been decided for the cluster and this node has not applied it. The statement does not fail at once. It waits for the node to apply the change, holding no lock, and then answers the new shape, as a statement on a single node waits for the lock of an ALTER TABLE in flight. It is refused only when the wait ends first: at its lock_timeout or its statement_timeout, whichever is shorter, or after an hour when it set neither. A statement that only reads the catalog (information_schema, pg_class, pg_attribute and the other relations that describe tables, columns, constraints, indexes, types and routines) and names no table with a change standing waits at most [cluster] truncate_node_timeout (two minutes by default) when it set no timeout; a view of the running system (pg_stat_activity, pg_locks, pg_settings) never waits, so a node whose change is stuck stays readable. A refused statement read and wrote nothing: run it again. The node keeps trying to apply the change by itself, a table the change does not touch is served meanwhile, and scramdb_cluster_ddl_apply_stuck above 0 for long is the sign to read the node's log (see Observability). See Read freshness and routing for the freshness rule behind it.
A SELECT, INSERT, UPDATE, DELETE or MERGE that names a table, view or sequence another node has just made gets the same answer instead of 42P01 when this node has not applied the CREATE and is still behind at the end of the statement's wait; what that check covers is on Changing a table on a cluster, and what it does not is on Not yet supported.
Two conflicting commits never wait for each other in a way that could deadlock: when they meet, the younger one gives way at once, so the conflict is reported as 40001, never as 40P01 (deadlock_detected), which ScramDB raises only for a real cycle among waiting locks. A transaction that keeps losing is retried older each time on the same session, so it eventually wins.
40001 is not only a cluster code: a single node running REPEATABLE READ or SERIALIZABLE raises the exact same SQLSTATE, with PostgreSQL's own wording, whenever a transaction's snapshot has gone stale by the time it tries to write. A REPEATABLE READ transaction that would overwrite a row a concurrent transaction already committed a newer version of gets could not serialize access due to concurrent update; a SERIALIZABLE transaction refuses with could not serialize access due to read/write dependencies among transactions whenever any table it read was written by another transaction after its own snapshot was taken. That check is conservative read validation, not cycle detection: it refuses strictly more than a real write-skew detector would, never less, so a SERIALIZABLE transaction can be aborted here even without a genuine cycle. Both are Definite in exactly the sense above: the aborted transaction left no effect, so re-executing it from the start is safe. This is the same single-node MVCC contract every PostgreSQL client already retries on.
A second writer on a row a REPEATABLE READ or SERIALIZABLE transaction is already touching does not fail immediately: it waits for the row's holder, bounded by lock_timeout. If the wait times out, the second writer gets 55P03 (lock_not_available). If the holder commits first, the waiter then gets 40001 as described above, never a silently lost update. A deadlock (two transactions each waiting on a row the other holds) gets 40P01 (deadlock detected), as in PostgreSQL, but at once instead of after deadlock_timeout: the transaction whose lock request completes the deadlock receives the error, and the other one goes on.
On a distributed table, whichever of two conflicting writers commits second gets 40001 at its COMMIT, at every isolation level, READ COMMITTED included. Neither 55P03 nor 40P01 comes from a row of a distributed table. See Row locks on distributed tables.
SQLSTATE 08007: transaction_resolution_unknown
Hint, fixed for every cause below except the last: the transaction's outcome is UNKNOWN and it may still commit; reconnect and verify before any retry - a blind retry can double-apply. The last cause carries the change stands on the cluster.
Every one of these is InDoubt: the commit (or, for the last, the table change) was sent, and this connection could not learn what became of it. The cluster itself always decides the transaction, committed or not, once its shard groups can be reached again; only this client does not know which. A transaction block that changed the schema keeps its schema changes pending, and its locks held, until the node that ran it learns the outcome; its shard groups keep the commit until then, however long the node stays cut off, so the block's changes end exactly as its commit did.
| Cause | Message shape |
|---|---|
The commit's round made no progress for its patience (at least [cluster.transactions] commit_answer_timeout, default 10 seconds; every vote recorded starts it again), or the session's statement_timeout passed since the commit was sent, and the node's question about the transaction's outcome was not answered within outcome_query_timeout (default 1 second), for example while a shard group's replicas cannot reach each other | the transaction's outcome is not known yet; it may still commit |
| The node's commit protocol stopped while the commit was in flight | the transaction's outcome is not known yet; it may still commit |
| The server's log could not confirm that the commit's record was written (a failed sync of the log), on a single node or on a cluster node. A table statement answers the same when one of its records is already in the log and the next was refused for room, or when its record may still be written later | the transaction's commit record could not be confirmed as written ({cause}); it may still commit |
| A schema change the cluster decided, whose statement then could not confirm that every node took it: a shard group of this node did not take the change in time, or this node has not finished applying it | the table change was made on the cluster, but the statement could not confirm it on every node; check the result before running the statement again (or ... but this node has not finished applying it yet: it is still being applied here; check the result before running the statement again), hint the change stands on the cluster |
The last cause is the log's own. The commit's record may or may not be in the log file, so the server answers in doubt and shows the commit to no session while it runs. Whether the record is there is only known later, and a restart can still find it: read your data back to see whether the transaction is there, and run it again only if it is not or if it is safe to apply twice. Every commit that was waiting on the same failed sync answers the same way, and a commit whose record was already durable before the failure is acknowledged and read as usual. The log writes the records again into a new file by itself, so a commit that waited only for a sync that this repaired answers committed and never shows this error; see SQLSTATE 58030.
The cause after it is a table change, not a commit. The cluster has decided the change, so it stands on every node: a node that did not take it in time keeps trying by itself and shows it on scramdb_cluster_ddl_apply_stuck. The statement answers 08007 and not a plain error, because sending it again is the wrong move (an ALTER TABLE ... ADD COLUMN sent again meets the column it added, 42701). Read the table's definition to see the change, and run the statement again only if it is not there.
A cancel that arrives while a COMMIT waits for its answer does not cut the wait short, and a statement_timeout ends it only by asking for the outcome: once the commit is sent, the client is told its outcome (or 08007), never a cancellation of a commit that may have happened. The same holds for COMMIT PREPARED.
For a non-idempotent effect (a payment, an email, a call to an external API), the correct response to 08007 is never a bare retry counter: reconnect, verify whether the write actually landed, and only replay it if it is safe to apply twice or is itself protected by a dedupe key.
SQLSTATE 57P01: admin_shutdown
Hint: this node is shutting down; reconnect to another node
The node the client was talking to is draining, whether from an operator-initiated drain or an ordinary shutdown, or its commit protocol stopped. The statement never reached the cluster, so nothing needs undoing; the fix is to reconnect somewhere else. Message shape: node is draining: {detail}. See Failover for what a client experiences end to end when a node goes away.
A node that can never start a transaction (the cluster has no node number left to give it, or the file that keeps its transaction numbers unique cannot be read or written) answers with the same code and hint connect to another node, message shape this node cannot run transactions: {detail}. It keeps refusing until an operator fixes the cause, so reconnect elsewhere.
SQLSTATE 57P03: cannot_connect_now
Hint: the cluster is not serving yet; back off and reconnect
The cluster, specifically its own metadata group, has not finished forming yet, or this node has not yet been given the number its transactions are named by. Both are startup-time conditions, not something a running cluster produces once it is up. Message shape: cluster is not ready: {detail}.
The same code and message shape cover one more case, at any time a cluster is otherwise healthy: a statement named a cluster table whose shard assignment has not reached this node's own view of the cluster's placement yet - just after the table was created elsewhere, or just after this node restarted and is still catching up with the cluster's metadata group. The statement waits for the assignment itself, for up to [cluster.transactions] commit_answer_timeout (10 seconds by default), and then runs as usual; it answers this way only when the assignment did not arrive in that time, which means this node cannot reach the cluster's metadata group. Detail: table "{name}" is not placed on this node yet; retry the statement. Nothing was read or written; retry the statement, or connect to another node. For COMMIT PREPARED the prepared transaction then stays prepared, and running COMMIT PREPARED again commits it.
A running cluster answers 57P03 for one more reason: this node's copy could not catch up in time for a read. A read waits until this node's copy of every shard group it reads has applied what the read needs; when that does not happen within the read's wait (about ten seconds with the default settings), the read is refused with hint retry the statement, or connect to another node and message this node's replica of shard group {n} is too far behind to serve the read. Nothing was read. Retry, or reconnect to another node.
No SQLSTATE: the connection just died
A dead socket is not a database error and carries no SQLSTATE, because no server ever got the chance to send one. The client's driver raises its own transport-level exception instead. This is, in practice, the single most common thing a client sees when a node is killed: a node that dies closes its sockets before it can answer anything.
What it means depends on when the connection died. Before your transaction sent COMMIT (or, outside a transaction block, before its writing statement was sent), nothing was decided: treat it exactly like 57P01, reconnect to a different node and re-execute. After COMMIT was sent, the outcome is unknown: a cluster commit is decided once every shard group the transaction touched holds a durable vote for it, not when the answer reaches the client, and a commit whose coordinating node died after that point is finished by the other nodes. Treat that case exactly like 08007: reconnect, verify whether it applied, and retry only if the write is idempotent or protected by the outbox recipe. A retry loop written only against the SQLSTATE table above, and not against this case, is the retry loop most likely to be wrong in production, because it is the one case with nothing to switch on.
SQLSTATE 40P01: deadlock_detected, across nodes
A deadlock in a single-node database is a cycle in one lock table. In a cluster the cycle can span nodes: transaction A on node 1 waits for a row locked by transaction B on node 2, which waits for a row locked by A. No single node's lock table can see that cycle, so without cluster-wide detection both transactions would wait until their lock timeouts expired, which reads to a client as an unexplained stall rather than a deadlock.
ScramDB registers every refused blocking lock acquisition as a wait edge in the replicated metadata group, so the whole waits-for graph is visible in one place. When a cycle appears, one transaction is chosen as the victim deterministically (every node picks the same one from the same graph, so the decision needs no extra round of agreement) and aborted with 40P01. The survivors proceed immediately rather than waiting out a timeout.
Wait edges are cleared when the lock is granted, and expire on their own if the waiting node disappears, so a dead node cannot leave a phantom edge that deadlocks live traffic.
Treat 40P01 exactly as you treat it in PostgreSQL: the victim left no effect, so re-execute it. If you see it often, the fix is lock-ordering discipline in the application, not a retry loop.
SQLSTATE 42704: undefined_object, from an unknown session parameter
This one is not a cluster failure, is not retryable; it belongs on this page because it is a case an AI coding agent probing session settings programmatically will hit. SET, SHOW and RESET all name the same parameter table, so a name the session does not recognize is refused the same way by every one of the three: SET nosuchparam = 'x', SHOW nosuchparam and RESET nosuchparam each return 42704 with the message unrecognized configuration parameter "{parameter}" and no hint text. A dotted name (a custom parameter in an extension's own namespace, for example myapp.flag) is always accepted by SET and RESET, whether or not it has been set before. SHOW is narrower: it looks the dotted name up in the session's own settings, so SHOW myapp.flag before anything has ever set it is also 42704 - only for SET and RESET is it only the unqualified name that must already be a known setting.
This is deliberately not an empty string, and SET is deliberately not a silent success either. Returning "" for an unknown parameter, or letting SET accept a name it does not recognize, is the less compatible behavior, not the more forgiving one: a caller that asks for a setting and gets an empty value back, or sets one that is quietly accepted and does nothing, may read that as a real, valid answer and act on it, silently. Every client that already targets PostgreSQL already knows how to handle 42704; returning it from all three commands is what makes an unrecognized parameter unambiguous instead of quietly wrong.
SQLSTATE 22007, 22008, 22009 and 22023: a date or time text that does not read
These are not cluster failures. One reader decides every date and time text for DATE, TIMESTAMP and TIMESTAMPTZ, in PostgreSQL's forms ('1/2/2024', '8.1.99', 'J2451187', '04:05 PM', month names, a zone written as an abbreviation, a name or a POSIX string). An ambiguous field is read in the order of the session's DateStyle (DMY, MDY or YMD), so the same text can read as two dates under two sessions, as in PostgreSQL; a prepared statement reads in the order of the session that runs it. A text no form reads is 22007, a field out of range 22008, a numeric zone offset out of range 22009, and a zone name that does not exist 22023 (time zone "x" not recognized). A DateStyle value the session refuses is 22023 with PostgreSQL's DETAIL (Unrecognized key word: "foo"., Conflicting "DateStyle" specifications.).
The order of a setting change's refusals
Every spelling of a setting change (SET, SET LOCAL, RESET, set_config, a routine's SET clause, a connection's startup options, ALTER ROLE ... SET, ALTER DATABASE ... SET, ALTER SYSTEM, GRANT ... ON PARAMETER) is checked against one catalog of the settings of PostgreSQL 18, and answers in PostgreSQL's order: an unknown name is 42704, a context that forbids the change is 55P02, a setting only a superuser (or a role granted it on the parameter) may change is 42501, and a value the setting refuses is 22023. pg_settings and SHOW ALL list the same catalog with each setting's context, type, unit, bounds, default and description.
SQLSTATE 54001: statement_too_complex, from a statement that nests too deep
This one is not a cluster failure. PostgreSQL rejects a pathologically deep expression, or a routine that recurses too deeply, before running any of it, with a clean error rather than a crash; ScramDB matches that behavior, HINT included.
A statement's own expression tree is checked before planning ever begins, against the stack its deepest path would take, which PostgreSQL's max_stack_depth session setting controls. As in PostgreSQL, a level takes a different share of the stack depending on what it is, so the depth that is refused depends on what is nested. At the 2048kB default, a chain of about 10,900 casts or IS NULL tests, about 8,100 NOTs, about 7,200 UNION ALL arms, about 4,600 nested ROW constructors, about 3,600 nested function calls or terms in a flat chain of + (1+1+1+...) and about 1,800 nested scalar subqueries is answered, and a deeper one is refused. A flat chain of AND or OR terms takes none of it, as in PostgreSQL. Lowering max_stack_depth tightens the check in proportion, and raising it loosens it, up to the limit in the next paragraph. Message: stack depth limit exceeded, with PostgreSQL's own HINT: Increase the configuration parameter "max_stack_depth" (currently 2048kB), after ensuring the platform's stack depth limit is adequate.
A statement nested past 16,384 levels in all is refused with the same error and HINT while it is still being read, whatever max_stack_depth says, and so is one of more than 100,000 expression nodes. PostgreSQL has no such limit on a chain of AND or OR terms or on an IN list, which it answers at any length it can hold, so one longer than either limit is refused here and answered there. The session survives the refusal and answers its next statement.
A chain of views, each reading the one before, is held to the same limit as it is read and planned, so the depth answered follows max_stack_depth as it does in PostgreSQL: at 100kB a read answers through 215 views and refuses a chain of 216, at 256kB through 572, at 1024kB through 2,327 and at the 2048kB default through 4,668. A read, EXPLAIN, a cursor, COPY (SELECT ...) TO, INSERT ... SELECT, a subquery of UPDATE or DELETE, CREATE TABLE AS or CREATE MATERIALIZED VIEW with data, and REFRESH MATERIALIZED VIEW are refused at the same depth, with the same message and HINT. A statement that only describes the query answers deeper: the Parse message of the extended protocol answers through 504 views at 100kB and the PREPARE statement through 499 (the statement is planned when it is executed, where the read's depth applies again), while CREATE VIEW, CREATE TABLE AS ... WITH NO DATA, CREATE MATERIALIZED VIEW ... WITH NO DATA and a read of information_schema.columns answer at any depth, as in PostgreSQL. A chain costs a fixed share of the stack per view, fit to PostgreSQL's answers; a statement of another shape holds a few views of stack more or less before its first view in PostgreSQL. A chain of more than 8,192 views is refused at any setting.
A function or procedure that recurses too deeply, whether through a direct self-call, PERFORM, or mutual recursion between routines, is refused the same way, with a message naming the depth reached. A trigger whose own body fires the same or another trigger again - a BEFORE INSERT trigger that inserts into the table it fired on, for instance - meets the identical bound: the recursion is refused with 54001 before it can grow without limit, and the statement that triggered it fails cleanly rather than leaving the session unusable.
Nesting the grammar itself cannot hold is a different case, and carries a different code: the parser refuses it, as PostgreSQL's own parser does, with a syntax error (SQLSTATE 42601), never 54001. Parentheses nested past about 10,000 levels get PostgreSQL's own memory exhausted at or near "(" wording; a nested CASE past the parser's stack gets an ordinary syntax error at or near ... instead, naming whatever token the parser gave up on. Thousands of levels of nesting are answered; only a pathological depth is refused.
Neither case is retryable as written: an ordinary statement is never refused by this check, so seeing it means the statement, or the recursive routine, genuinely needs to be smaller.
SQLSTATE 22003: numeric_value_out_of_range
This one is not a cluster failure. It is PostgreSQL's own code for an arithmetic result that does not fit its type, and ScramDB raises it for the same reasons PostgreSQL does: an integer, bigint, or smallint result outside its type's range (integer out of range, and the equivalent for the other widths), a floating-point result outside IEEE range (value out of range: overflow or ...: underflow), and a NUMERIC result past its precision, whether that precision is a declared NUMERIC(p,s) or PostgreSQL's own bound on an unconstrained NUMERIC (131,072 digits before the decimal point and 16,383 after: value overflows numeric format); a SUM or AVG whose total passes 38 significant digits still raises numeric field overflow. None of these are retryable as written: the value or the query needs to change.
SQLSTATE 57014: query_canceled
This one is not a cluster failure. Three independent sources feed the same cancellation: statement_timeout elapsing, a call to pg_cancel_backend(), and PostgreSQL's own out-of-band wire protocol CancelRequest (a client opens a second, unauthenticated connection and presents the backend's process id and secret key). All three interrupt a running statement, including one that is purely CPU-bound rather than waiting on I/O and one that is waiting for a row, table or advisory lock (the wait ends the moment the cancel lands, and the lock is never taken for the cancelled statement), and return 57014 with one of PostgreSQL's own two messages: canceling statement due to statement timeout or canceling statement due to user request. The session itself is unaffected and keeps answering; only the cancelled statement is aborted, so re-issue it if it should still run.
SQLSTATE 42883: undefined_function, from LIKE over a non-text operand
This one is not a cluster failure. PostgreSQL's ~~ operator family (LIKE, NOT LIKE, ILIKE, NOT ILIKE) exists for text and bytea only; ScramDB refuses the same way at planning, before a statement like int_col LIKE '%5%' or enum_col LIKE 'a%' ever runs, with a message naming the operand's real type: operator does not exist: {type} ~~ unknown (and the analogous ~~*, !~~, !~~* for ILIKE and the negated forms). Cast the operand to text first if a text comparison is genuinely what is wanted.
SQLSTATE 53100: disk_full
This one is not a cluster failure and is not covered by classify. A statement that failed because a write had no room to land - the storage device is full - answers 53100 with the message could not write: no space is left on the storage device, never a raw operating-system error string. The statement changes nothing: every row a previous statement committed stays exactly as it was and stays readable, whatever the failing statement was in the middle of writing. Free space on the storage device and re-execute the statement: writes resume by themselves once space returns, with no restart, and a commit refused for lack of room leaves none of its rows visible. The server logs one warning when writes stop and one line when they resume, and scramdb_wal_disk_full reads 1 while they are refused. This is the answer for every statement that writes: INSERT, UPDATE, DELETE, COPY in and out, DDL, GRANT and REVOKE, and a query that spills to a temporary file. None of them answers success for a change the store refused.
53100 says two things: nothing was done, and nothing will be written later. A commit, a DROP TABLE, a TRUNCATE, an ALTER TABLE ... RENAME TO and a restore point that the log had no room for are given up in the same way, so a drop, a truncate or a rename that answered 53100 is not found done after a restart. A background compaction whose record the log has no room for does not swap its segments: the table keeps the ones it had. CREATE TABLE is whole or absent: it succeeds, its records waiting in the log until there is room, or it answers 53100 or 08007 and leaves no table, and the same statement then goes through. A statement that had already put one of its records safely in the log when the next was refused cannot say which way it went, and neither can a statement whose record the log may still write later (a change of the catalog that another record can counter): each answers 08007 and not 53100, and you check the table before you run it again (see SQLSTATE 08007). A full disk never ends the log, whatever the size of the record it refused: the next write with room goes through.
SQLSTATE 2202E, 22004, 54000, 22P03 and 08P01: an array that does not fit PostgreSQL's array rules
These are not cluster failures. They are PostgreSQL's own codes and words for an array that cannot be built or read, and ScramDB raises them for the same reasons. 2202E is a multi-dimensional constructor whose sub-arrays differ in size (multidimensional arrays must have array expressions with matching dimensions), array_cat or array_agg over arrays whose dimensions do not fit (cannot concatenate incompatible arrays, cannot accumulate arrays of different dimensionality), a store outside a multi-dimensional array and a trim_array count out of range. 22004 is array_agg over a NULL array (cannot accumulate null arrays). 54000 is more than six dimensions or more elements than PostgreSQL allows. A binary array sent as a bind parameter or in COPY ... (FORMAT binary) is read as PostgreSQL's array_recv reads it, with any lower bound and up to six dimensions: a bad flag word, an element that does not decode, an element length that runs past the message or bytes left over is 22P03 (invalid array flags, improper binary format in array element N, insufficient data left in message, incorrect binary data format), an element type other than the column's is 42804 (wrong element type), and a message that ends inside the header words is 08P01 (insufficient data left in message). An array cast to a vector type that has more than one dimension or no element is 22000 (array must be 1-D, vector must have at least 1 dimension). Each refused statement changes nothing, and none of them is retryable unchanged.
SQLSTATE 57P05 and 25P03: a session closed for sitting idle
These are not cluster failures. They are PostgreSQL's codes for idle_session_timeout (57P05, terminating connection due to idle-session timeout) and idle_in_transaction_session_timeout (25P03), both off by default, as in PostgreSQL. Set them for the server under [resilience] or per session with SET; RESET returns to the server value. A session closed this way holds no locks afterwards: an open transaction is rolled back first.
SQLSTATE 58030 and XX001: a file or a prepared record that could not be used
These are not cluster failures. 58030 is PostgreSQL's io_error: a read or write the operating system failed, or a query that needs a spill file whose temporary directory cannot be written. The statement changes nothing, so re-executing it after the volume is healthy is safe.
58030 is also the answer of a write while the server's log is failed, that is, after a sync of the log failed and the server could not yet write its records again into a new file. The message is The server cannot write its log (cause); it serves reads only until its storage works again or it is restarted on working storage., and it is the same for every statement that writes (INSERT, UPDATE, DELETE, COPY in, CREATE TABLE, ALTER TABLE), alone or in a transaction block. The statement changes nothing and no session reads anything of it. Reads go on, a read-only block still commits, and every session reads exactly what the log made durable. A checkpoint is refused, scramdb_wal_failed reads 1 and /health answers 503 with the cause. A failure that was a full device answers 53100 instead.
Every statement that changes the catalog meets the log's state before it changes anything and gets the same answer: ALTER TABLE, COMMENT, GRANT, CREATE INDEX, CREATE SCHEMA, CREATE SEQUENCE, CREATE VIEW, CREATE FUNCTION, CREATE TABLE, CREATE DATABASE and DROP TABLE change nothing, and each goes through once the log has healed. A temporary table, view or sequence is the exception, since no record of the log covers it: it is made and read while the log is failed, and a transaction that wrote only temporary tables commits. A transaction that wrote a temporary table and a durable one is a durable write and is refused as any write is. A statement that changes no catalog (SET, SHOW, EXPLAIN, a read, a cursor, PREPARE, LISTEN) answers as on a healthy server.
The server does not wait for a restart. It tries to write its records again on a pause that starts at 100 milliseconds and doubles up to 10 seconds, and when its storage answers it takes writes again: scramdb_wal_failed returns to 0, /health returns to 200 and the statement you re-execute goes through. The statements that answered 08007 meanwhile are the ones to check first (see SQLSTATE 08007). A failed write of the log (rather than a failed sync) still stops it until the server is restarted on working storage; scramdb_wal_failed then stays at 1. A failure of the server's own storage path stops it the same way: the commits that waited behind it answer 08007, every later write answers 58030 with the cause, and the server logs one error line. Restart the server on working storage.
XX001 answers COMMIT PREPARED for a prepared transaction whose record is damaged or missing: ROLLBACK PREPARED ends it.
SQLSTATE XX000: an internal error that ended one statement
An internal error ends the statement that met it, never the server. The statement answers XX000 with internal error: {what} failed on an unexpected condition (statement shape {fingerprint}); the server log has details. The fingerprint is the masked statement shape the log line carries too, so the two can be matched. The statement is not retried by the server; report the fingerprint with the log line.
This contract is tested, not just asserted
The mapping above is pinned down by tests that fail if any code or class in this table drifts: every way a commit can end is checked against its exact contracted SQLSTATE and retry class, a conflict between two commits is asserted to be 40001 and never 40P01, a transaction that never reached a commit is asserted never to be in doubt, and the availability and default codes are checked against this same table. Real clusters answer the same codes over the wire.