What does the Postgres 'too many clients' error actually mean?
Postgres refuses a new connection at the authentication stage when its fixed pool of backend slots is full. Each connection is a separate server process, and max_connections caps how many can exist at once. The exact wording differs slightly between versions, but the variants you will see map to distinct conditions:
| Message (approximate) | What triggered it | Who can still connect |
|---|---|---|
FATAL: sorry, too many clients already |
Every slot under max_connections is taken |
Nobody |
FATAL: remaining connection slots are reserved for ... superuser ... |
Only the slots held back by superuser_reserved_connections are left |
Superusers only |
FATAL: too many connections for role "..." |
A per-role CONNECTION LIMIT was hit |
Other roles |
FATAL: too many connections for database "..." |
A per-database connection limit was hit | Other databases |
The reserved-slot message usually appears first. Ordinary roles are cut off while a few slots remain, so an administrator can still log in during an incident, query pg_stat_activity, and terminate offending sessions. If your services connect as a superuser, they can consume those reserved slots too, and you lose that way in. Application roles should not be superusers.
This checklist rests on one claim: the error is almost never evidence that max_connections is too low. It means connections are being held too long, for example by sessions sitting idle in transaction, or opened too widely, for example by too many replicas each running an oversized pool.
The checklist is for backend and platform engineers who own services that share a database. In that setup, one team's connection leak takes down everyone else's service.
Who should use this checklist?
Use it if any of the following describes your role or your system:
- On-call engineers who get paged for
too many clientsorremaining connection slots are reservederrors and need a repeatable sequence of queries and decisions instead of improvising under pressure. - Backend engineers who write the code that opens transactions and checks connections out of a pool. Most of the root causes covered here, such as leaked connections and transactions held open across external calls, live in application code.
- Platform and database engineers who run a Postgres server shared by several services or teams. They control server-side timeouts, per-role and per-database connection limits, monitoring, and whether a pooler sits in front of the database.
- Teams adopting autoscaling or serverless compute. Scaling out the number of processes multiplies the number of connection pools, so a design that worked at a fixed replica count can start exhausting connections without any code change.
If you run a single application against a dedicated database with a small, fixed number of processes, you may never hit this error. The sections on timeouts and monitoring still apply, because a single stuck idle in transaction session causes lock and vacuum problems regardless of how many connections you have.
How does Postgres connection handling work?
Postgres uses a process-per-connection model. A main server process listens for incoming connections. When a client connects, the server starts a new backend process dedicated to that client. The backend authenticates the client, then serves every query on that connection, one at a time, until the client disconnects or the session is terminated.
The number of client backends that can exist at once is bounded by max_connections. The server sizes its shared-memory structures for that many backends when it starts, which is why changing max_connections requires a restart rather than a reload. A few of those slots are held back by superuser_reserved_connections, so ordinary roles are refused before the server is completely full.
A connection occupies its slot for its whole lifetime, whether it is doing work or not. A backend that is idle, or idle in transaction, holds a slot exactly as firmly as one running a query. This is the mechanism behind most exhaustion incidents: the server is rarely out of capacity to execute queries, but it is out of slots because clients are holding connections they are not using.
Application connection pools sit on the client side of this model. A pool opens a set of real server connections and lends them to application code. Each pool caps only its own process, so the server sees the sum of every pool in every process on every host. External poolers sit between clients and the server and can let many client connections share a smaller number of server backends, which the pooler section covers.
How do you triage connection exhaustion with pg_stat_activity?
When the server refuses new clients, you can usually still connect through a slot held back by superuser_reserved_connections. Use it to run one aggregate over pg_stat_activity: count client backends grouped by state, usename, datname, application_name and client_addr, sorted by count descending. A single row with hundreds of sessions points at the service, host or user to investigate first. A blank application_name hides which service a session belongs to, so ask teams to set it in their connection strings.
Then read the state column:
| State | What the backend is doing | Holds locks? | Blocks vacuum cleanup? |
|---|---|---|---|
active |
Executing a query | Yes, while running | Yes, while running |
idle |
Connected, no open transaction | No | No |
idle in transaction |
Transaction open, waiting on the client | Yes, everything acquired so far | Yes |
idle in transaction (aborted) |
A statement failed and the client has not rolled back | Yes, until rollback | Yes |
idle in transaction is the most dangerous state. The session uses a connection slot while doing no work. It keeps every lock it has taken, so other sessions queue behind it and take up more slots. Its open snapshot also stops vacuum from removing dead rows that newer transactions created, which causes table bloat. To rank these sessions by age, sort by now() - xact_start. The state_change column shows how long each session has been in its current state.
pg_stat_activity only shows the current moment. If the spike has already passed, the view may show nothing unusual. You need sampled metrics or logs to reconstruct what happened.
-- 1. Who is holding the connections? Run this from a reserved superuser slot.
SELECT state,
usename,
datname,
coalesce(nullif(application_name, ''), '<unset>') AS application_name,
client_addr,
count(*) AS sessions
FROM pg_stat_activity
WHERE backend_type = 'client backend' -- skip autovacuum, walsender, etc.
GROUP BY state, usename, datname, application_name, client_addr
ORDER BY sessions DESC
LIMIT 20;
-- 2. Which open transactions are oldest? These hold slots and locks,
-- and stop vacuum from removing dead rows.
SELECT pid,
usename,
application_name,
client_addr,
state,
now() - xact_start AS xact_age, -- age of the open transaction
now() - state_change AS in_state_for, -- time spent in the current state
left(query, 80) AS last_query -- last statement the session ran
FROM pg_stat_activity
WHERE state IN ('idle in transaction', 'idle in transaction (aborted)')
ORDER BY xact_start
LIMIT 20;
Two first-response queries against pg_stat_activity: one groups client sessions by state, user, database, application and client address so one source stands out, and the other ranks idle-in-transaction sessions by transaction age.
How do you find the session holding connections and safely release it?
When the sessions are still there, sort them by age. xact_start is when the current transaction began, query_start is when the latest statement began, and state_change is when the session last switched state. Ordering by now() - xact_start in descending order puts the oldest open transactions first, and those are usually the problem. A session in idle in transaction with an xact_start from twenty minutes ago is holding a connection slot, and possibly locks, while doing nothing.
Read the query column next. For an active session it shows the statement that is running. For an idle session it shows the last statement that ran. If a stuck session's last query was a SELECT followed by nothing, the application probably opened a transaction, read some data, and then never committed. That tells you which code path to look at.
There are two ways to release a session:
pg_cancel_backend(pid)cancels the running query and leaves the connection open. It is useful for a runaway query. It does nothing for anidle in transactionsession, because no query is running.pg_terminate_backend(pid)ends the session and frees the slot.
Terminate specific idle in transaction sessions by PID. Avoid bulk kills such as "every connection from this application." Terminating a session rolls back its uncommitted work, so a bulk kill throws away legitimate in-flight writes along with the stuck ones. It also disconnects many clients at once. If they all reconnect immediately, the retry storm can fill max_connections again within seconds.
-- 1. List the oldest open transactions first.
SELECT pid,
usename,
application_name,
client_addr,
state,
now() - xact_start AS xact_age,
now() - state_change AS in_state_for,
now() - query_start AS since_last_query,
left(query, 80) AS last_query
FROM pg_stat_activity
WHERE xact_start IS NOT NULL
AND pid <> pg_backend_pid()
ORDER BY now() - xact_start DESC
LIMIT 20;
-- 2. Runaway query on an active session: cancel the query only.
-- The connection stays open. This has no effect on idle sessions.
SELECT pg_cancel_backend(12345);
-- 3. Stuck session: end it and free the slot.
-- Uncommitted work in that transaction is rolled back.
SELECT pg_terminate_backend(23456);
-- 4. If there are several, target only idle-in-transaction sessions
-- that have been idle long enough. Review the step 1 output first.
SELECT pid, pg_terminate_backend(pid) AS terminated
FROM pg_stat_activity
WHERE state = 'idle in transaction'
AND now() - state_change > interval '10 minutes'
AND pid <> pg_backend_pid();
Rank sessions by transaction age in pg_stat_activity, then cancel a runaway query or terminate specific idle-in-transaction sessions by PID instead of killing connections in bulk.
Why doesn't raising max_connections fix the problem?
Each connection is served by its own backend process with its own private memory, so the limit is also a cap on how many processes compete for RAM, CPU and locks. work_mem makes this worse: it is allotted per sort or hash operation, not per connection, so a single complex query can use several multiples of it. Raising max_connections from 200 to 1,000 multiplies that worst case by five while shared buffers and CPU stay the same. Changing it also requires a server restart, so you can't adjust it during an incident without downtime.
Exhaustion usually comes from the sum of many reasonable-looking pools: pool size per process × processes per instance × instances, plus everything else that connects.
Illustrative estimate (assumed inputs, max_connections = 300):
| Client | Assumed sizing | Connections |
|---|---|---|
| API pods, normal load | 10 per process × 4 processes × 3 pods | 120 |
| API pods, autoscaled | 10 × 4 × 8 pods | 320 |
| Background workers | 2 instances × 10 | 20 |
| Cron jobs | 5 concurrent × 1 | 5 |
| Migration runner | 2 | 2 |
| Admin tools, dashboards | 3 | 3 |
| Total at peak | 350 |
At normal load the total is 150. After scale-out it reaches 350, even though no single pool is larger than 10. Superuser-reserved slots lower the usable ceiling further.
Raising the limit is still a reasonable short-term measure when three conditions hold: you have confirmed the demand is legitimate rather than a leak, there is measured memory headroom, and you can schedule the restart. Treat it as a bridge until you cap per-instance pools or add a pooler.
+-----------------------------------+
| API pods: 8 x 4 procs x pool 10 |--- 320 --+
| (normal load: 3 pods = 120) | |
+-----------------------------------+ |
| Background workers: 2 x 10 |--- 20 --+
+-----------------------------------+ |
| Cron jobs: 5 concurrent x 1 |--- 5 --+
+-----------------------------------+ |
| Migration runner |--- 2 --+
+-----------------------------------+ |
| Admin tools, dashboards |--- 3 --+
+-----------------------------------+ |
| peak demand: 350
v (normal load: 150)
+-------------------------------------------+
| PostgreSQL max_connections = 300 |
| (minus reserved slots) |
| |
| one backend process per connection: |
| +------+ +------+ +------+ +------+ |
| | proc | | proc | | proc | ... | proc | |
| +------+ +------+ +------+ +------+ |
| each has private memory; work_mem is per |
| sort or hash op, not per connection |
+---------------------+---------------------+
|
v
connections beyond limit: too many clients
Illustrative estimate with assumed inputs: no client pool exceeds 10 connections, yet autoscaled API pods plus workers, cron jobs, migrations and admin tools demand 350 connections against a max_connections of 300, and each connection is a separate backend process with its own memory.
Which application-side bugs leak or hoard connections?
Most connection exhaustion traces back to a handful of code-level patterns. Check each one:
- Connections not returned on error paths. A connection acquired at the top of a handler and released at the bottom leaks whenever an exception skips the release. Use your language's scoped construct (
try/finally, context manager,defer) so every exit path, including failures, returns the connection to the pool. - Transactions held open during external I/O. This is the usual source of
idle in transactionsessions. Here is the wrong pattern: begin a transaction, read a row, call a payment API or upload to object storage, then write and commit. The connection sits idle, holding locks, for as long as the slow call takes. The right pattern is to make the external call first, or between two short transactions, so each transaction covers only database work. - ORM sessions scoped too broadly. A session that lives for the whole request, background job or worker process holds a connection far longer than the queries need it.
- Pools with no maximum. An unbounded pool turns traffic spikes directly into new server connections.
- Short-lived processes that connect without pooling. Serverless functions, cron scripts and migration jobs each open fresh connections. At high concurrency they can exhaust the server without any single process misbehaving.
When you fix a leak at the source, it stays fixed. That saves the engineering time you would otherwise spend triaging the same exhaustion incident each time it recurs.
Shrinking pools has a cost. A smaller pool moves the queue from Postgres into your application: requests wait for a free connection, and tail latency rises. Size each pool against observed query duration and request concurrency, not only by dividing max_connections across instances.
from psycopg_pool import ConnectionPool
pool = ConnectionPool("postgresql://app:changeme@db.internal:5432/shop",
min_size=2, max_size=10, timeout=5)
def charge_card(order_id, amount):
... # slow external payment API call (placeholder)
def pay_order_wrong(order_id):
with pool.connection() as conn, conn.transaction():
amount = conn.execute(
"SELECT amount FROM orders WHERE id = %s FOR UPDATE", (order_id,)
).fetchone()[0]
charge_card(order_id, amount) # session sits 'idle in transaction' here
conn.execute("UPDATE orders SET status = 'paid' WHERE id = %s", (order_id,))
def pay_order_right(order_id):
# 1. Read (and mark in-progress) in a short transaction.
with pool.connection() as conn, conn.transaction():
amount = conn.execute(
"UPDATE orders SET status = 'charging' WHERE id = %s AND status = 'pending' "
"RETURNING amount", (order_id,)
).fetchone()[0]
# Connection is back in the pool, even if an exception was raised above.
# 2. Slow external call with no database connection checked out.
charge_card(order_id, amount)
# 3. Record the result in a second short transaction.
with pool.connection() as conn, conn.transaction():
conn.execute("UPDATE orders SET status = 'paid' WHERE id = %s", (order_id,))
Using psycopg 3's bounded ConnectionPool, the wrong version holds a transaction open across a slow payment API call, while the right version splits the work into two short transactions and relies on context managers to return the connection on every exit path, including errors.
Which server-side timeouts and limits should you set?
Two timeouts do most of the work. idle_in_transaction_session_timeout terminates any session that has opened a transaction and then stopped sending queries for longer than the limit. This targets the classic leak: a request handler that issues BEGIN, hits an exception path, and never commits or rolls back. Postgres closes the session, which frees the connection slot and releases its locks. statement_timeout cancels individual statements that run too long. It does not close the connection, but it stops one slow query from holding a pooled connection indefinitely while new requests queue behind it.
Scope the settings
Avoid aggressive values in postgresql.conf. A 30-second statement_timeout that protects your API will also cancel a schema migration, a monthly report, or a backfill job halfway through. Set the timeouts where the workload is predictable instead:
ALTER ROLE api_service SET statement_timeout = '5s'applies only to that service's logins.ALTER DATABASE app SET idle_in_transaction_session_timeout = '60s'applies to every session in one database.- Batch and migration roles get longer limits, or none, through their own
ALTER ROLE ... SET.
These settings apply to new sessions, so existing pooled connections keep the old values until they reconnect.
Cap connections per tenant
ALTER ROLE worker CONNECTION LIMIT 40 and ALTER DATABASE analytics CONNECTION LIMIT 60 stop one service or database from consuming every slot on a shared server. The cost is how failure looks. When a service hits its cap during a traffic spike, its new connections are rejected immediately. Without the cap, all services would slow down together as the server ran short of slots. The cap is usually the right choice, but that service's pool and retry logic must handle the rejection.
When should you add a connection pooler, and what are the alternatives?
An external pooler earns its place when the number of client processes, not query load, drives connection count: dozens of service replicas each holding a pool, horizontal autoscaling that multiplies pools during traffic spikes, or serverless functions that each open a connection. In those cases per-process pools cannot coordinate, so the total grows with the number of processes rather than with demand.
| Approach | What it fixes | What it costs |
|---|---|---|
Raise max_connections |
Immediate rejections | More memory per backend, more contention; no reduction in waste |
| Server-side limits only | Keeps one client from starving the others | Clients still get errors; fewer connections in total |
| In-application pooling only | Reuse within one process | Totals scale with replica count |
| Pooler, session mode | Centralises the cap | A client holds its backend for the whole session, so the gain is small |
| Pooler, transaction mode | Many clients share few backends | Session state no longer persists between transactions |
Transaction pooling hands your next transaction to whichever backend is free. Session-level SET, session advisory locks, LISTEN/NOTIFY, temporary tables, and prepared statements (depending on the pooler and driver configuration) can end up on a different backend from the one where they were created. These problems rarely raise clean errors. They show up as a wrong search_path, a lock that seems to be ignored, or missing notifications.
The pooler is also another component to deploy, monitor and make highly available. Its own client and backend limits can become the new bottleneck. Its queueing can hide the real cause, such as a session left idle in transaction, behind vague latency.
What should you monitor to catch connection exhaustion early?
A pg_stat_activity snapshot only shows the moment you run it. Connection spikes often last seconds, and a burst that exhausted the server at 03:12 may be gone by the time someone runs a query at 03:20. Collect the following metrics every 15–30 seconds and store them as time series. That gives you a record of what happened and when.
Three alerts worth having
- Connections as a percentage of
max_connections. Use a percentage instead of an absolute count so the alert stays valid when the limit changes. Alert below 100%, for example at 80%. This leaves headroom before normal clients are refused, since superuser-reserved slots don't help your application. - Count of
idle in transactionsessions. A rising count with flat traffic usually means a code path opened a transaction and never committed or rolled back. - Age of the oldest open transaction. Use the maximum of
now() - xact_start. It catches a single stuck session that a count would hide. Long transactions also hold locks and block vacuum cleanup.
A single query against pg_stat_activity can return all three. Count rows by state, compare the total to current_setting('max_connections'), and take the maximum transaction age. Restrict it to client backends so background workers don't distort the numbers.
On-call recap
- Confirm the error and check connection usage against the limit.
- Group sessions by
state, application, user, and client address. - Find the oldest transaction and identify what holds it.
- Cancel the query first. Terminate the backend only if cancelling doesn't release it.
- Trace the holder to the code path that leaked it.
- Add timeouts, per-role limits, or a pooler. Don't just raise the limit.
How can this checklist save engineering time?
Connection exhaustion is expensive mainly because it tends to recur and because each occurrence pulls several people into the same investigation. The checklist cuts that cost in a few specific ways:
- Faster triage. Keeping the
pg_stat_activityqueries in a runbook means on-call engineers run a known query from a reserved slot instead of writing one during an outage. Requiring every service to setapplication_nameturns "which service is it?" from a cross-team discussion into a single row in the query output. - Fewer escalations across teams. On a shared server, per-role
CONNECTION LIMITsettings confine an exhaustion event to the service that caused it. One team handles its own incident instead of every team that shares the database being paged at once. - Less manual cleanup. Scoped
idle_in_transaction_session_timeoutandstatement_timeoutsettings release stuck sessions automatically, so nobody has to find and terminate them by hand at night. - No restart-driven fixes. Because
max_connectionschanges require a restart, treating the limit as the fix means scheduling downtime and repeating it as demand grows. Fixing pool sizing and leaks avoids that cycle. - Root causes fixed once. Tracing an incident to a specific pattern, such as a transaction held open across an external API call, produces a code change that removes that class of incident. Restarting the application or raising the limit only resets the clock.
- Earlier warning. Alerts on connection percentage,
idle in transactioncount, and oldest transaction age surface a leak while there is still headroom, when the fix can be a normal code change instead of an emergency.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to postgres too many clients, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.