Postgres 'Remaining Connection Slots Are Reserved' Error: Fix
Postgres says remaining connection slots are reserved for superusers and your app is down? Find who holds the connections, free them, and size your pools so it stays fixed.
The error FATAL: remaining connection slots are reserved for non-replication superuser connections means your app has used every connection Postgres allows for normal users. Connect as a superuser or admin, run a query on pg_stat_activity to see which app or user holds the connections, end the idle ones, then reduce your pool sizes or add a pooler such as PgBouncer. Raising max_connections only buys time.
Postgres has a hard ceiling. Normal roles can use max_connections minus superuser_reserved_connections. The rest are kept so an admin can still log in during a crisis. When your app hits that line, every new request that needs the database fails, and the site looks down even though the database is healthy. This guide is for small teams without a DBA.
Step 1: Get In and See the Numbers
Use the admin account or the platform's SQL editor. Superusers can use the reserved slots. Then compare current use against the limit:
SHOW max_connections;
SHOW superuser_reserved_connections;
SELECT count(*) FROM pg_stat_activity;
If the count is close to max_connections minus the reserved number, you have confirmed the cause. On managed services the limit depends on your plan size. The Supabase docs for this error note that it appears when you reach the connection cap of your compute tier.
Step 2: Find Who Holds the Connections
Group by user, application and state:
SELECT usename, application_name, state, count(*)
FROM pg_stat_activity
WHERE pid <> pg_backend_pid()
GROUP BY 1, 2, 3
ORDER BY count(*) DESC;
Look for one client with a very large count. Many rows in idle means a pool or a script is holding connections it does not use. Rows in idle in transaction are worse. They hold locks and never give the connection back. Common culprits are a cron script that opens a connection per run, a worker with a huge pool, a dashboard tool left open, and serverless functions that each open their own connection.
Step 3: Free Connections Right Now
To recover quickly, end old idle sessions:
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state IN ('idle', 'idle in transaction')
AND state_change < now() - interval '10 minutes'
AND pid <> pg_backend_pid();
Check what you are about to kill. Do not run this against sessions that belong to a long import or a migration. Your app's pool will reconnect on its own.
Step 4: Add Up Your Pools
The usual root cause is arithmetic. Each app instance has a pool. Total connections are instances times pool size, plus workers, plus cron jobs, plus your own SQL client. Ten instances with a pool of 20 is 200 connections, which is more than a default Postgres allows. List every process that connects, multiply, and keep the total well under the limit. If you run Node, our connection pool exhaustion guide shows how to size and monitor pools. MySQL has the same problem under another name, covered in MySQL error 1040.
Step 5: Put a Pooler in Front
If you run serverless functions or many short-lived processes, application pools cannot help, because each process has its own. A pooler such as PgBouncer (or Supavisor on Supabase) shares a small number of real connections across many clients. Use transaction mode for web traffic. Be aware that transaction mode does not support session features like prepared statements in some drivers, so test before switching. The Pulse guide and the OneUptime article both recommend pooling over raising limits.
Step 6: Fix Leaks and Idle-in-Transaction Sessions
If connections climb back up after you free them, you have a leak. Look for code that opens a connection and does not close it on an error path. Use context managers or finally blocks. Set timeouts so a stuck session cannot live forever:
ALTER ROLE app_user SET idle_in_transaction_session_timeout = '60s';
This ends sessions that sit inside a transaction doing nothing. It protects you from one buggy request holding a slot.
Step 7: Raise the Limit Only After the Above
You can raise max_connections, but each connection uses memory, and more connections can slow the server down. Treat it as a short patch. On managed Postgres, upgrading the plan raises the cap. On a self-hosted server, edit postgresql.conf and restart. Postgres 16 and later also has reserved_connections for roles granted pg_use_reserved_connections, which lets you reserve slots for a monitoring or admin role. Check your version before relying on it.
Step 8: Alert Before You Hit the Wall
The error only appears at 100 percent. Alert on connection use at around 80 percent so you have time to act. A simple check is the count(*) query above against max_connections, run every minute by your monitoring tool.
A Quick Checklist After the Fix
Once the app is back, write down what held the connections and why. Check four things before you close the incident. First, the total of all pool sizes is below the limit with room to spare. Second, background workers and cron scripts use small pools of their own, not the web app's settings. Third, your deploy process does not start new instances before old ones stop, which briefly doubles the connections. Fourth, your SQL client and dashboard tools use the pooled connection string, not a direct one. These four causes explain most repeat incidents, and each takes a few minutes to check. If you keep a short postmortem, our incident postmortem template fits this case well.
How Relia Helps
When connections run out, the symptom is a burst of failed requests across unrelated pages. Relia watches the users, APIs, database and servers of a live product and joins related signals, such as a deploy followed by failing requests and a database problem, into one incident explained in plain words, with who was affected. Setup for Node.js and browser apps is npx relia-sdk@latest init, and Relia has a Python package and a Composer package for PHP and Laravel. There is a Free plan and a live demo at app.tryrelia.com/demo.
FAQ
What does "remaining connection slots are reserved" mean in Postgres?
Normal users have no free connections left. Only the slots kept for superusers remain.
How do I check how many connections Postgres is using?
Run SELECT count(*) FROM pg_stat_activity; and compare with SHOW max_connections;.
Should I just increase max_connections?
Only as a temporary step. Each connection costs memory. Fix leaks and pool sizes, or add a pooler, first.
Why does this happen with serverless functions?
Each function instance opens its own connections, and many instances can run at once. A pooler in front of the database solves it.
What is the difference between "too many clients already" and this error?
"Too many clients already" appears when even superuser slots are full. This error appears when only the reserved slots are left.