Incident brief
Too many connections
A non-superuser connection attempt arrived after every non-reserved connection slot was already in use. PostgreSQL rejected it so the reserved slots stay available for superuser roles.
In 10 seconds
- What triggers it
- With max_connections = 100 and superuser_reserved_connections = 3 (both defaults), open 97 connections with a non-superuser role and hold them open.
- Fix
- Raise max_connections (requires a restart) if the application genuinely needs more concurrent connections.
- Proof
- Reproduced on PostgreSQL 16.14 → With every non-reserved connection slot (97 of 100, since 3 are reserved for superusers) held open by a non-superuser role, one more connection attempt with that role was rejected with SQLSTATE 53300.
Fix
What to do right now
Application-level steps for this error.
- Raise max_connections (requires a restart) if the application genuinely needs more concurrent connections.
- Put a connection pooler (e.g. PgBouncer) in front of PostgreSQL so application connections are reused instead of each request opening a new one.
- Don't 'fix' this by lowering superuser_reserved_connections to 0, see the premium counterexample for exactly what that gives up.
-- Prefer a pooler (PgBouncer/ODS) so apps reuse backends instead of opening one per request.
-- If you must raise the hard limit (requires restart):
-- ALTER SYSTEM SET max_connections = 200;
-- -- then restart PostgreSQL; pg_reload_conf() is not enough
-- Keep superuser_reserved_connections > 0 so admins can still connect when the pool is full.
SHOW max_connections;
SHOW superuser_reserved_connections;
SELECT count(*) AS current_connections FROM pg_stat_activity;For this error
See this error live on the server
Run these against the affected instance to confirm the diagnosis before you act.
Separate total connection pressure from active work and preserve superuser/reserved slots. The application-side fix is pooling or reducing fan-out, not only raising max_connections.
Connections by state and role
Find which roles/applications own the connection budget and how many are merely idle.
SELECT usename, application_name, state, count(*) AS connections
FROM pg_stat_activity
WHERE backend_type = 'client backend'
GROUP BY usename, application_name, state
ORDER BY connections DESC;Configured connection ceiling and reserved slots
Calculate usable client slots rather than comparing only with max_connections.
SELECT current_setting('max_connections')::int AS max_connections,
current_setting('superuser_reserved_connections')::int AS superuser_reserved,
current_setting('reserved_connections', true) AS reserved_connections,
(SELECT count(*) FROM pg_stat_activity) AS current_backends;PgBouncer queue and server pool
Run on the PgBouncer admin database. cl_waiting plus maxwait shows queued clients; sv_active/sv_idle shows how many PostgreSQL backends serve them.
SHOW POOLS;
SHOW SERVERS;Why it happens
What PostgreSQL is telling you
The mechanism behind the error, grounded in the official manual, not paraphrased.
PostgreSQL 16 Documentation, Connection Settings (19.3)
superuser_reserved_connections ... Determines the number of connection 'slots' that are reserved for connections by roles with the SUPERUSER attribute.Read the full section on postgresql.org →
Confirming 97 connections are held
max_connections is 100 and superuser_reserved_connections is 3, so 97 slots are available to ordinary roles, this confirms all 97 are in use before the next attempt.The 98th connection attempt (rejected)
With every non-reserved slot in use, PostgreSQL rejects any further non-superuser connection attempt with SQLSTATE 53300, keeping the 3 reserved slots free.Reproduce & verify
A real reproduction with every non-reserved slot exhausted
A literal transcript of SQL run against a live PostgreSQL instance in an isolated lab. The commands below are exactly what was executed.
- 1With max_connections = 100 and superuser_reserved_connections = 3 (both defaults), open 97 connections with a non-superuser role and hold them open.
- 2Attempt one more connection with that same non-superuser role.
- 3SQLSTATE 53300 is reported: the remaining slots are reserved for superuser roles.
97 real connections held open by a non-superuser role (100 max_connections minus 3 superuser_reserved_connections), then one more connection attempted with the same role.
CREATE ROLE batch8_conn_test_user LOGIN PASSWORD 'test123';
-- then 97 background connections, each holding: SELECT pg_sleep(30);SELECT count(*) FROM pg_stat_activity WHERE usename = 'batch8_conn_test_user';psql -U batch8_conn_test_user -d thesev1database -c "SELECT 1;"What PostgreSQL actually returned
CREATE ROLE count
-------
97
(1 row)psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: remaining connection slots are reserved for roles with the SUPERUSER attributeThe deeper lab audit for this error
- What the reserved slots are actually for: exact SQL, output, and verdict
- A manual-grounded production interpretation of the lab result
Card required. Cancel before day 7 and you are not charged.
Runbook to fix this
Runbooks for this incident
Full step-by-step fixes for the condition behind this error: the diagnosis, the exact SQL, and output captured in the lab.
- Diagnose PgBouncer queueing and session-state leaksClients wait in PgBouncer even though PostgreSQL has capacity, or session settings behave inconsistently.Free
- Survive a connection storm when there is no poolerConnections pile up, the app times out, and CPU is high while throughput sits flat.Free
- Find what is actually burning CPUCPU is pinned at 100% and every session looks busy, but you cannot name the query.Pro
Connected
Everything this error touches
Every page this SQLSTATE connects to: the concept that explains it, the runbooks that fix it, the parameters you tune to prevent it, and the sibling errors it travels with. All real cross-references. Jump straight in, or open the full interactive map.
Understand the concept
Fix it — runbooks
Tune to prevent it
Related errors
Verification
- Last verified
- 2026-07-16 (Docker lab, PostgreSQL 16.14)
- Verification scope
- Verified against PostgreSQL 16.14 in an isolated lab environment
- Audit status
- reviewed
Went further?
Pro unlocks the second lab proof
Free page stops the bleeding. Pro adds the operational test, SQLSTATE audit, and deeper evidence, same error, more certainty.