PostgreSQL: FATAL — sorry, too many clients already

Hi, it's BlueByte. The app was fine an hour ago, and now every new connection dies with FATAL: sorry, too many clients already. Nothing is corrupted — the sessions already open keep working, PostgreSQL just has no free slot to hand out. We'll walk through that line and its variants, how to count what is holding your slots, the fix for each cause, and how to keep the pool from filling again.

What the FATAL line means when Postgres turns a client away

The rejection happens before any query runs:

psql: error: connection to server at "db.internal" (10.0.3.12), port 5432 failed:
FATAL:  sorry, too many clients already

You may see a different wording:

FATAL:  remaining connection slots are reserved for non-replication superuser connections
FATAL:  remaining connection slots are reserved for roles with the SUPERUSER attribute
FATAL:  remaining connection slots are reserved for roles with privileges of the "pg_use_reserved_connections" role

All carry SQLSTATE 53300 (too_many_connections) and mean the same thing to your app: no slot for you. The wording follows your major version — PostgreSQL 16 added the reserved_connections setting and the pg_use_reserved_connections role, splitting the older single message into the two newer ones. If your driver surfaces only the SQLSTATE, match on 53300.

Where the connection slots actually go

max_connections is a hard ceiling, typically 100 and lower if initdb found a tighter kernel limit — and not what your app gets, because the reserve comes off the top. superuser_reserved_connections defaults to three, and on 16 and later reserved_connections defaults to zero, leaving 97 slots for ordinary roles.

Four things consume them:

• Pools multiplied by replicas. Every app process keeps its own pool: ten pods with a pool of ten is a hundred connections while the site sits idle.
• Sessions parked in an open transaction. A request that opens a transaction and waits on an external API holds its slot the whole time.
• Leaked connections from migration jobs, a forgotten psql, BI dashboards, and crashed workers whose sockets haven't timed out.
• Short-lived clients reconnecting faster than they disconnect — cron jobs, serverless functions, health checks that open a connection per invocation.

Count what is connected before you change a setting

Don't raise max_connections until you know what is on the other end. Connect as a superuser — the reserve exists so you still can — and ask:

SHOW max_connections;
SHOW superuser_reserved_connections;
 
SELECT state, count(*) FROM pg_stat_activity
 WHERE backend_type = 'client backend'
 GROUP BY state ORDER BY count DESC;

        state        | count
---------------------+-------
 idle                |    71
 idle in transaction |    19
 active              |     7

That shape is the diagnosis. Mostly idle means oversized pools. A large idle in transaction count means the app opens transactions and waits on something slow. Mostly active means you are genuinely at capacity and need a pooler or a bigger server. Then find the owners:

SELECT usename, application_name, client_addr, count(*)
FROM pg_stat_activity WHERE backend_type = 'client backend'
GROUP BY 1, 2, 3 ORDER BY 4 DESC LIMIT 10;

Free the slots that idle transactions are holding

If idle in transaction dominates, those sessions burn a slot and hold back vacuum at once. List the worst offenders first:

SELECT pid, usename, now() - state_change AS idle_for, left(query, 50) AS last_query
FROM pg_stat_activity
WHERE state = 'idle in transaction' AND now() - state_change > interval '5 minutes'
ORDER BY idle_for DESC;

Terminating one rolls its open transaction back and closes the socket; a healthy client reconnects. It is safe on an idle session — nothing is executing — but read last_query first, since a paused migration looks identical to a leak:

SELECT pg_terminate_backend(pid) FROM pg_stat_activity
WHERE state = 'idle in transaction' AND now() - state_change > interval '15 minutes';

Then let the server enforce it — this takes effect on reload, no restart:

ALTER SYSTEM SET idle_in_transaction_session_timeout = '60s';
SELECT pg_reload_conf();

The docs are blunt: an open transaction "prevents vacuuming away recently-dead tuples," so a long idle costs table bloat on top of the slot. The sibling setting idle_session_timeout covers sessions idle outside a transaction, but the docs warn to "be wary of enforcing this timeout on connections made through connection-pooling software" — leave it off if a pooler sits in front.

Cap the client side instead of raising the ceiling

The durable fix is usually fewer connections, not more slots. Budget them: pool size across every replica, plus migrations, plus humans, must stay under max_connections minus the reserve. If that arithmetic doesn't work, put a pooler in front so many clients share a few server connections:

[databases]
app = host=10.0.3.12 port=5432 dbname=app
 
[pgbouncer]
listen_port = 6432
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20

Point the app at port 6432 and a thousand client connections ride on twenty server slots. Transaction pooling buys that ratio and changes behaviour: anything tied to a session rather than a transaction — LISTEN, advisory locks, prepared statements held across transactions — needs checking first.

When raising max_connections is the right answer

Sometimes the traffic is real and 100 is simply small. Raise it, but know the cost: the docs note PostgreSQL "sizes certain resources based directly on the value of max_connections," shared memory included, so a big jump raises memory use before any client arrives.

ALTER SYSTEM SET max_connections = 200;

sudo systemctl restart postgresql
psql -Atc 'SHOW max_connections;'

200

The restart is not optional — the docs state this parameter "can only be set at server start," so a plain reload leaves the running value untouched while ALTER SYSTEM quietly records the new one. On managed services the value comes from a parameter group derived from instance size: change it there, not in postgresql.conf, and check your provider's default instead of assuming 100.

A real case: a deploy that tripled the worker count

An API scaled from 4 pods to 12 on a Friday afternoon. Each pod's driver kept a pool of 10, so the fleet wanted 120 connections against max_connections = 100. New logins failed with sorry, too many clients already while already-connected pods kept serving — which is why it looked intermittent. pg_stat_activity showed 96 client backends, 88 of them idle, all with the same application_name: nothing leaked, the pools were just too big for the new replica count. Dropping the per-pod pool to 5 brought steady state to about 60 and connections recovered in seconds.

Confirm it held, and keep the pool from filling again

Watch the headroom:

SELECT count(*) AS used,
       current_setting('max_connections')::int AS ceiling,
       round(100.0 * count(*) / current_setting('max_connections')::int, 1) AS pct
FROM pg_stat_activity;

Under 80 percent at peak is comfortable. Alert on it, keep idle_in_transaction_session_timeout set, and give batch work its own role with ALTER ROLE etl CONNECTION LIMIT 5 so one runaway script can't take the server down.

How this differs from the per-role and per-database limits

Two neighbours share SQLSTATE 53300 but have nothing to do with max_connections. FATAL: too many connections for role "app" comes from a per-role cap set with ALTER ROLE ... CONNECTION LIMIT; check SELECT rolconnlimit FROM pg_roles WHERE rolname = 'app'. FATAL: too many connections for database "app" is the same per database, stored as datconnlimit in pg_database. In both the server can be nearly empty, so raising max_connections changes nothing. If the message mentions reserved slots, you are at the ceiling minus the reserve — an ordinary role is blocked while a superuser still gets in, which is what the reserve is for.