How to fix Serialization failure in PostgreSQL

PostgreSQLINTERMEDIATEMEDIUMUpdated Dec 28, 2025· 216 views

Serialization failures occur when concurrent transactions conflict in PostgreSQL's Serializable or Repeatable Read isolation levels. Retrying the complete transaction from the beginning is the recommended fix.

Quick fix

Fixes 40001

const MAX_RETRIES = 3;
let retries = 0;

while (retries < MAX_RETRIES) {
  try {
    await client.query('BEGIN ISOLATION LEVEL SERIALIZABLE');
    // Your transaction logic here
    await client.query('COMMIT');
    break;
  } catch (error) {
    if (error.code === '40001') {
      retries++;
      if (retries >= MAX_RETRIES) throw error;
      await client.query('ROLLBACK');
    } else {
      throw error;
    }
  }
}
  1. Implement transaction retry logic
  2. Add indexes to frequently queried columns
  3. Consider using Repeatable Read isolation
  4. Use DEFERRABLE for read-only transactions
postgresql — error
const MAX_RETRIES = 3;
let retries = 0;
while (retries < MAX_RETRIES) {
  try {
    await client.query('BEGIN ISOLATION LEVEL SERIALIZABLE');
    // Your transaction logic here
    await client.query('COMMIT');
    break;
  } catch (error) {
    if (error.code === '40001') {
      retries++;
      if (retries >= MAX_RETRIES) throw error;
      await client.query('ROLLBACK');
    } else {
      throw error;
    }
  }
}
Serialization failure

What this error means

A serialization failure (SQLSTATE 40001) happens when PostgreSQL detects that executing concurrent transactions would produce an inconsistent result if they were allowed to complete. PostgreSQL uses Serializable Snapshot Isolation (SSI) to monitor concurrent transactions and prevent serialization anomalies. When a conflict is detected between concurrent transactions that would violate serialization guarantees, PostgreSQL rolls back one of the transactions to ensure data consistency.

Typical symptoms

  • Transactions are unexpectedly rolled back with error code 40001
  • Application receives "could not serialize access" error messages
  • High frequency of transaction failures when using Serializable or Repeatable Read isolation levels
  • Read-only transactions fail even though they don't modify data
  • Transaction failures increase under heavy concurrent load

Common causes

  1. Multiple concurrent transactions modify overlapping rows with Serializable or Repeatable Read isolation
  2. Read-write transaction conflicts detected by SSI monitoring
  3. Sequential table scans requiring relation-level predicate locks that conflict with other transactions
  4. Read-only transaction sees a database state that cannot exist in any serial transaction schedule
  5. Missing indexes on frequently queried columns forcing sequential scans

How to fix "Serialization failure"

1Implement transaction retry logic

Catch serialization failures and retry the entire transaction from the beginning. This is the recommended approach as the second attempt will see previously-committed changes.

javascript
const MAX_RETRIES = 3;
let retries = 0;

while (retries < MAX_RETRIES) {
  try {
    await client.query('BEGIN ISOLATION LEVEL SERIALIZABLE');
    // Your transaction logic here
    await client.query('COMMIT');
    break;
  } catch (error) {
    if (error.code === '40001') {
      retries++;
      if (retries >= MAX_RETRIES) throw error;
      await client.query('ROLLBACK');
    } else {
      throw error;
    }
  }
}
2Add indexes to frequently queried columns

Sequential scans force relation-level predicate locks that increase serialization conflicts. Create indexes on columns involved in transaction queries:

sql
CREATE INDEX idx_users_account_id ON users(account_id);
CREATE INDEX idx_orders_user_id ON orders(user_id);

This allows index-level locks instead of relation-level locks, reducing false positive conflicts.

3Consider using Repeatable Read isolation

If Serializable isolation causes excessive failures, evaluate if Repeatable Read is sufficient for your use case. Repeatable Read prevents phantom reads but is less strict than Serializable:

sql
BEGIN ISOLATION LEVEL REPEATABLE READ;
-- your transactions
COMMIT;

Note: Repeatable Read can still produce serialization failures but typically at lower rates.

4Use DEFERRABLE for read-only transactions

If you have long-running read-only transactions, use the DEFERRABLE option to avoid serialization failures:

sql
BEGIN ISOLATION LEVEL SERIALIZABLE, READ ONLY, DEFERRABLE;
-- your read-only queries
COMMIT;

The session will wait for interfering read-write transactions to complete before starting, guaranteeing no serialization failure.

5Optimize transaction scope and duration

Reduce the window of potential conflicts by minimizing transaction duration:

- Keep transactions as short as possible
- Move non-database logic outside the transaction
- Break large operations into smaller transactions when safe
- Avoid user interactions inside a transaction

Shorter transactions reduce the overlap window with concurrent transactions.

6Monitor for idle transactions

Identify transactions holding locks that may cause conflicts:

sql
SELECT pid, usename, state, query, state_change 
FROM pg_stat_activity 
WHERE state = 'idle in transaction';

Terminate long-running idle transactions to reduce lock contention and serialization conflicts.

Advanced notes

Advanced considerations: Serializable isolation relies on indexes for granular predicate locking. Without proper indexing, PostgreSQL uses relation-level locks which dramatically increase false positive serialization failures. If experiencing high serialization failure rates, check your random_page_cost and cpu_tuple_cost parameters to encourage index usage. Under SSI, performance degrades with large numbers of active transactions; consider using connection pooling to limit concurrent connections. For advisory locking scenarios, also consider retrying SQLSTATE 40P01 (deadlock_detected), 23505 (unique_violation), and 23P01 (exclusion_violation) errors.

Frequently asked questions

What does "40001" mean?
A serialization failure (SQLSTATE 40001) happens when PostgreSQL detects that executing concurrent transactions would produce an inconsistent result if they were allowed to complete. PostgreSQL uses Serializable Snapshot Isolation (SSI) to monitor concurrent transactions and prevent serialization anomalies. When a conflict is detected between concurrent transactions that would violate serialization guarantees, PostgreSQL rolls back one of the transactions to ensure data consistency.
How do I fix "40001"?
Serialization failures occur when concurrent transactions conflict in PostgreSQL's Serializable or Repeatable Read isolation levels. Retrying the complete transaction from the beginning is the recommended fix.
What causes "40001"?
Multiple concurrent transactions modify overlapping rows with Serializable or Repeatable Read isolation Read-write transaction conflicts detected by SSI monitoring Sequential table scans requiring relation-level predicate locks that conflict with other transactions
Is the "40001" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading