PostgreSQL Insufficient Resources (SQLSTATE 53000)

PostgreSQL raises errors in class 53 — Insufficient Resources — whenever the server cannot fulfill a request because it has run out of a critical resource. The generic parent code is SQLSTATE 53000 with condition name insufficient_resources, but in practice PostgreSQL almost always raises one of the more specific subclass codes: 53100 (disk_full), 53200 (out_of_memory), 53300 (too_many_connections), or 53400 (configuration_limit_exceeded). A bare 53000 typically means a driver or middleware is reporting the class code without a more specific condition.

What This Error Means

Error class 53 is PostgreSQL's way of signalling that a requested operation cannot proceed because a finite server-side resource has been exhausted. Unlike class 42 (syntax errors) or class 23 (integrity constraint violations), class 53 errors are not caused by bad SQL — they reflect an operational or capacity problem that usually requires action outside the database session itself.

When a 53xxx error occurs, the current transaction is aborted. Any work done in that transaction is rolled back, and the client must issue a ROLLBACK before the connection can be reused. The connection itself is not dropped (unlike a FATAL error), so application connection pools will still hold a usable connection after a ROLLBACK.

Because 53000 is a parent class rather than a leaf condition, seeing it verbatim usually means something in the stack (a JDBC driver, a PgBouncer log line, an ORM exception mapper) is reporting only the class portion of the SQLSTATE. The actual PostgreSQL server log will almost always show a more specific 531xx or 534xx code that points to the real cause.

Common Causes

1. Disk full (53100) — A tablespace, WAL directory, or temporary file area runs out of space. PostgreSQL raises ERROR: could not write to file "base/pgsql_tmp/pgsqlXXXX": No space left on device and cancels the query.

2. Out of memory (53200) — The server exhausts work_mem for a sort or hash operation, or the OS kills the postmaster via the OOM killer. You will see messages like ERROR: out of memory or DETAIL: Failed on request of size N in memory context "ExprContext".

3. Too many connections (53300) — All max_connections slots are occupied. New connection attempts receive FATAL: sorry, too many clients already. This is the most frequently encountered class-53 error in production.

4. Configuration limit exceeded (53400) — A resource guard defined by a GUC (e.g., max_locks_per_transaction, max_prepared_transactions) is breached. For example: ERROR: out of shared memory when the lock table is full.

5. Temporary file limit (temp_file_limit) — A query exceeds the per-session temp_file_limit GUC, causing PostgreSQL to abort the query rather than let a single session consume unbounded disk space.

6. Shared memory exhaustion — Insufficient shared_buffers, max_wal_size, or OS SHMMAX/SHMALL settings prevent PostgreSQL from allocating its shared memory segment at startup or during operation.

How to Fix insufficient_resources

Because 53000 is a class umbrella, the fix depends on which specific subclass you are actually hitting. Start by reading the full error message in pg_log or via pg_stat_activity.

1. Identify the specific subclass first.

   -- Find recently blocked or errored queries
   SELECT pid, state, wait_event_type, wait_event, query_start, query
   FROM pg_stat_activity
   WHERE state <> 'idle'
   ORDER BY query_start;
   

2. For disk full (53100): Free space in the relevant tablespace or mount point. Identify large tables or indexes:

   SELECT relname, pg_size_pretty(pg_total_relation_size(oid))
   FROM pg_class
   WHERE relkind IN ('r','i')
   ORDER BY pg_total_relation_size(oid) DESC
   LIMIT 20;
   

   Also check for bloated WAL (pg_wal/) or leftover temp files in pg_tmp.

3. For out of memory (53200): Lower work_mem to reduce per-sort allocation, or increase OS memory. Check for queries sorting large result sets without proper indexes:

   -- In postgresql.conf or per-session:
   SET work_mem = '64MB';   -- default is 4MB; tune carefully
   

   Use EXPLAIN (ANALYZE, BUFFERS) to find sorts or hash joins spilling to disk.

4. For too many connections (53300): Deploy a connection pooler (PgBouncer in transaction mode is the standard solution). In the short term, identify idle connections holding slots:

   SELECT count(*), state, wait_event_type
   FROM pg_stat_activity
   GROUP BY state, wait_event_type
   ORDER BY count DESC;
   

   Terminate idle connections if needed:

   SELECT pg_terminate_backend(pid)
   FROM pg_stat_activity
   WHERE state = 'idle'
     AND query_start < now() - interval '10 minutes';
   

5. For configuration limit exceeded (53400): Increase the relevant GUC in postgresql.conf and reload. Common culprits:

   # postgresql.conf
   max_locks_per_transaction = 256     # default 64
   max_prepared_transactions = 100     # default 0 (disabled)
   

   After editing, reload with SELECT pg_reload_conf(); or pg_ctl reload.

6. For temp file limits: Either raise temp_file_limit (set to -1 to remove the cap) or tune queries to avoid large sorts/hash aggregates:

   # postgresql.conf — per-database or per-role override is also possible
   temp_file_limit = -1    # no limit; set a positive value in kB to re-enable
   

Additional Information

• Class 53 has existed since early PostgreSQL releases. The 53400 subclass (configuration_limit_exceeded) was added in PostgreSQL 9.4 to distinguish GUC-related resource caps from raw OS exhaustion.
• Related SQLSTATE codes in the same class:
  • 53100 — disk_full
  • 53200 — out_of_memory
  • 53300 — too_many_connections
  • 53400 — configuration_limit_exceeded
• JDBC drivers (pgjdbc) map all class-53 codes to PSQLException with SQLState set to the specific subclass. Spring's SQLExceptionTranslator maps them to DataAccessResourceFailureException.
• PgBouncer surfaces 53300 as its own FATAL: no more connections allowed message before the connection even reaches PostgreSQL; the SQLSTATE in client libraries will still be 53300.
• Monitoring: track pg_stat_activity connection counts, filesystem utilization for tablespace mount points, and pg_stat_bgwriter.checkpoint_write_time for I/O pressure that can precede disk-full conditions.

Frequently Asked Questions

Why does my application show SQLSTATE 53000 when the PostgreSQL log shows 53300? The application or driver is reporting only the class portion of the SQLSTATE (the first three characters). The server always emits the full five-character code. Check your driver's exception-handling configuration — most drivers expose both the full SQLSTATE and the message string; log both for easier diagnosis.

Can a class-53 error corrupt my data? No. PostgreSQL aborts the current transaction when a class-53 error occurs, rolling back any partial changes. Data already committed before the error is safe. However, a disk-full condition can prevent WAL writes, which in extreme cases can cause PostgreSQL to shut down entirely to protect data consistency — so disk monitoring is important.

My EXPLAIN shows a hash join — could that trigger an out-of-memory error? Yes. Hash joins and hash aggregates build an in-memory hash table bounded by work_mem. If a single sort or hash phase exceeds work_mem, PostgreSQL writes a temporary file (a "spill"). If temp_file_limit is set and that spill exceeds it, you get 53000/53200. Add appropriate indexes, reduce result set size before the join, or increase work_mem for that specific session.

What is the fastest way to resolve too many connections in production right now? Terminate long-running idle connections with pg_terminate_backend() (see fix step 4 above), then install PgBouncer as a permanent fix. Raising max_connections is a short-term workaround that increases shared memory pressure and can degrade performance — it is not a substitute for connection pooling.