CockroachDB 'restart transaction' Error (40001) Fix

How to fix it

// try these in order, the most common fix is first

1. FIX 1Add a client-side retry loop

   Copy steps
   1. 01Catch errors with SQLSTATE 40001 (message contains 'restart transaction')
   2. 02Retry the whole transaction with exponential backoff and a max_retries limit
   3. 03Test it by enabling the inject_retry_errors_enabled session setting
   Did this fix it? Yes No

2. FIX 2Let CockroachDB retry for you

   Copy steps
   1. 01Send all statements of the transaction in one batch so automatic retry can work
   2. 02Keep result sets under 16KB and avoid reading large results mid-transaction
   3. 03Keep transactions short
   Did this fix it? Yes No

3. FIX 3Reduce contention

   Copy steps
   1. 01Find hot rows on the DB Console Insights / Transactions pages
   2. 02Avoid sequential keys; use UUIDs or hash-sharded indexes
   3. 03Split counters across several rows
   Did this fix it? Yes No

4. FIX 4Try READ COMMITTED

   Copy steps
   1. 01Enable READ COMMITTED isolation where your app tolerates it
   2. 02READ COMMITTED transactions do not return serialization errors that need client-side handling
   Did this fix it? Yes No

Symptoms

ERROR: restart transaction: TransactionRetryWithProtoRefreshError; SQLSTATE 40001; transactions fail under load but work alone.

Why it happens

• C-01Concurrent writes to the same rows (hot keys) under SERIALIZABLE isolation
• C-02Multi-statement transactions that take several round trips and cannot be auto-retried
• C-03Result sets over 16KB sent before the transaction finished
• C-04Long-running transactions that touch many rows
• C-05No retry logic in the application or ORM

// this guide also covers

• cockroachdb restart transaction
• cockroachdb 40001
• TransactionRetryWithProtoRefreshError
• cockroachdb serialization failure
• cockroachdb transaction retry error

The same problem in other apps

All not loading, error messages & connection guides →

• PlanetScale Prisma Connection Errors (PlanetScale)

Other CockroachDB errors

• CockroachDB Cluster Throttled: License Expired or No Telemetry
• Why Is CockroachDB Slow? Slow Query Fixes
• CockroachDB Connection Refused / Cannot Connect Fix
• CockroachDB Node Down or Cluster Unavailable: Fix
• CockroachDB High Memory, CPU or OOM Crash Fix
• CockroachDB 'Not Supported' / Postgres Compatibility Errors Fix
• CockroachDB Cloud Bill Too High: How to Cut Costs
• How to Cancel or Downgrade CockroachDB Cloud