- Software and digital services
- Databases
40001
PostgreSQL 40001 serialization_failure: transaction conflict
Evidence linked to this decision
View source: PostgreSQL 18 Appendix A: Error CodesRisk level
Medium
Proceed carefully and stop if the check is unclear.
Urgency
Medium
Quick answer
PostgreSQL returns 40001 (serialization_failure) when it aborts a Repeatable Read or Serializable transaction to prevent a concurrency anomaly. Check your transaction handler first so it issues ROLLBACK and replays the whole transaction from the initial read.
Safety first
Stop and check this first
- Never treat data read inside a Serializable transaction as final before COMMIT succeeds (unless the transaction is declared SERIALIZABLE READ ONLY DEFERRABLE); do not trigger external payments or emails before commit.
- Do not attempt to silence 40001 by disabling constraints, triggers, or durability settings such as fsync, and always roll back the failed transaction before starting a retry.
Safe checks you can perform
- Inspect the exact 40001 error text and active transaction isolation level
- Verify whether the application retries the entire transaction after ROLLBACK
- Check pg_locks for SIReadLock granularity and lingering prepared or idle transactions
Leave these tasks to a qualified professional
- Do not attempt this professional task: Implement whole-transaction retry and read-only optimization in application code
- Do not attempt this professional task: Tune predicate lock capacity and idle-in-transaction timeouts on the server
What a technician must be able to justify
Technician visit
These are the steps they must carry out and show you. Tick them as they work: if steps are skipped, do not accept a part swap.
These are not instructions for opening or handling the equipment yourself. They are the checks that should support a technical conclusion.
Implement whole-transaction retry and read-only optimization in application code
What they doHave the application engineering team wrap Repeatable Read and Serializable workflows in a bounded retry loop that issues ROLLBACK on 40001 and re-runs all reads and business logic, while marking read-only transactions as READ ONLY (and SERIALIZABLE READ ONLY DEFERRABLE for batch reports).
They must show youthe transaction wrapper diff, test logs proving a simulated 40001 triggers a full rollback and replay, and query plans showing index scans instead of sequential scans.
In writingthe maximum retry count, backoff policy, and the list of transactions declared READ ONLY or DEFERRABLE.
Tune predicate lock capacity and idle-in-transaction timeouts on the server
What they doHave the DBA evaluate whether predicate lock promotion is driving 40001 spikes and, after capacity review and a configuration backup, adjust max_pred_locks_per_transaction, max_pred_locks_per_relation, max_pred_locks_per_page, or idle_in_transaction_session_timeout.
They must show youthe before-and-after values from SHOW max_pred_locks_per_transaction, pg_locks SIReadLock granularity counts, and transaction rollback rates in pg_stat_database.
In writingthe exact postgresql.conf parameter changes, the planned restart window required for max_pred_locks_per_transaction, and the rollback plan.
Before accepting a part or repair
Nothing has been shown yet. Do not accept a part swap based on the code alone.
Follow these steps
Note: Follow the documented order. An error code identifies the affected system, but it does not prove by itself which part has failed.
Inspect the exact 40001 error text and active transaction isolation level
- Who:
- You or your application developer inspecting the failed request log and session configuration.
- How:
- Read the server error message paired with SQLSTATE 40001 and run SHOW transaction_isolation in a read-only session, redacting passwords, connection strings, and personal data before saving any log excerpt.
- Result that matters:
- Whether the message says could not serialize access due to concurrent update or could not serialize access due to read/write dependencies among transactions.
- If the error message mentions concurrent update under Repeatable Read or Serializable mode, that confirms two sessions modified or locked the same target rows after the transaction snapshot started.
- If the error message mentions read/write dependencies among transactions, that points to a Serializable dependency cycle detected through SIReadLock predicate locks rather than a direct row write wait.
- Evidence to keep:
- Keep the timestamped 40001 log line, the output of SHOW transaction_isolation, and the redacted SQL statements from the aborted unit of work.
Never lower isolation to Read Committed or disable application integrity checks without verifying business rules first; run only read-only SHOW commands during initial triage.
Evidence: PostgreSQL 18 Appendix A: Error Codes · PostgreSQL transaction isolation · PostgreSQL 18 SHOW
Verify whether the application retries the entire transaction after ROLLBACK
- Who:
- Your developer reviewing the database client retry wrapper and transaction boundary code.
- How:
- Trace how the application handles SQLSTATE 40001 from the moment the error arrives to the next BEGIN statement, without replaying non-idempotent external API calls before commit.
- Result that matters:
- Whether the handler issues ROLLBACK and re-executes the complete transaction including all initial SELECT queries and value calculations.
- If the code only re-sends the failed UPDATE or INSERT statement inside the same transaction or with stale read values, that confirms an incomplete retry design that cannot resolve 40001 safely.
- If the handler rolls back and replays the entire transaction from the first read with fresh snapshot data, that rules out a missing retry loop and isolates the problem to high contention or long transactions.
- Evidence to keep:
- Save the code path reference, retry counter log, and transaction duration measurements for the failing endpoint.
Do not attempt automatic statement-level retries on 40001; re-running only the last SQL statement without recomputing earlier reads can write inconsistent data.
Evidence: PostgreSQL transaction isolation · PostgreSQL ROLLBACK · PostgreSQL 18 serialization failure handling
Check pg_locks for SIReadLock granularity and lingering prepared or idle transactions
- Who:
- Your DBA or developer with read access to system monitoring views.
- How:
- Query pg_locks for mode = 'SIReadLock' and check pg_stat_activity for sessions lingering in idle in transaction while 40001 spikes occur.
- Result that matters:
- Whether predicate locks are escalated to relation level or overlapping transactions remain open for long periods.
- If pg_locks shows relation-level SIReadLock entries on busy tables, that indicates sequential scans or predicate lock promotion are widening conflict scope across Serializable sessions.
- If pg_locks shows tuple or page locks alongside old open transactions or prepared transactions, that points to long-lived sessions holding overlapping snapshots open.
- Evidence to keep:
- Record a snapshot of the pg_locks lock modes, relation names, and pg_stat_activity transaction age values.
Never terminate production backends or alter lock configuration parameters during this read-only check; redact query parameters containing personal data before sharing results.
Evidence: PostgreSQL transaction isolation · PostgreSQL 18 cumulative statistics system · PostgreSQL 18 serialization failure handling
Still not solved
If the error persists, stop here. See what the technician must do and show you.
Virtual technician
Does 40001 still appear after these checks?
This guided flow uses the exact code and your answers to choose a test, an expected result and the next branch.
Where this code applies
A code is meaningful only inside the right product and version context.
Primary scope
- System
- Software and digital services
- Brand
- PostgreSQL
- Product type
- Databases
Known code variants
- PostgreSQL 40001
- serialization_failure
- SQLSTATE 40001
What it means
Appendix A places 40001 (serialization_failure) in Class 40, Transaction Rollback. Under Repeatable Read or Serializable isolation, the server aborts a transaction when a concurrent session commits an overlapping row update or creates a read/write dependency cycle tracked by SIReadLock predicate locks. Because PostgreSQL cannot replay application branching logic safely on its own, the client session must roll back and run the entire transaction again. Receiving 40001 only signals a concurrency conflict between overlapping transactions and never proves by itself that the database server, storage layer, or SQL syntax is faulty.
Warnings and stop conditions
- Mediumsource verified
Never treat data read inside a Serializable transaction as final before COMMIT succeeds (unless the transaction is declared SERIALIZABLE READ ONLY DEFERRABLE); do not trigger external payments or emails before commit.
Evidence: PostgreSQL transaction isolation · PostgreSQL 18 serialization failure handling
- Highsource verified
Do not attempt to silence 40001 by disabling constraints, triggers, or durability settings such as fsync, and always roll back the failed transaction before starting a retry.
Evidence: PostgreSQL ROLLBACK · PostgreSQL 18 serialization failure handling
Symptoms and causes
Probable causes · in order
- Concurrent row modification during a Repeatable Read transactionCommon
In Repeatable Read mode, an UPDATE, DELETE, MERGE, SELECT FOR UPDATE, or SELECT FOR SHARE statement waits if another transaction is modifying the target row, and aborts with 40001 if that concurrent updater commits.
Evidence: PostgreSQL transaction isolation · PostgreSQL 18 serialization failure handling
- Read/write dependency cycle across Serializable transactionsCommon
Under Serializable isolation, PostgreSQL monitors SIReadLock predicate locks and rolls back one transaction with 40001 whenever committing all concurrent transactions would violate serial execution order.
Evidence: PostgreSQL transaction isolation · PostgreSQL 18 serialization failure handling
- Predicate lock promotion from sequential scans or lock table pressurePossible
Sequential scans force relation-level predicate locks, and low memory in the predicate lock table controlled by max_pred_locks_per_transaction (default 64) combines page locks into relation locks, raising false serialization conflicts.
Evidence: PostgreSQL transaction isolation · PostgreSQL 18 lock management settings
Sources and technical references
- 1
PostgreSQL 18 Appendix A: Error Codes
PostgreSQL Global Development Group · 2026 · official_doc
- 2
PostgreSQL transaction isolation
PostgreSQL Global Development Group · 2026 · official_doc
- 3
PostgreSQL Global Development Group · 2026 · official_doc
Was this entry useful?