Home/Error Library/postgresql-too-many-clients

PostgreSQL

PG 14 - 17Connection & Pool

5 min read

FATAL: sorry, too many clients already

PostgreSQL "too many clients already": Root Cause, Emergency Triage & Permanent Mitigation

Three root causes of FATAL: sorry, too many clients already, single diagnostic query to identify the cause, and permanent mitigation via max_connections and PgBouncer.

Reviewed by:Senior Database Architect & SRE (dataiotech Labs)

Tested Versions: PostgreSQL 14.10, 15.6, 16.4, 17.0 (Ubuntu 24.04 LTS / Docker 26.1)

Operational Verification & Reliability Metadata

Last Technical Review: 27 Ekim 2026

Tested VersionsPostgreSQL 14.10, 15.6, 16.4, 17.0 (Ubuntu 24.04 LTS, Docker 26.1, Kernel 6.8)

Required PrivilegesSUPERUSER or pg_read_all_stats / pg_signal_backend

Risk Assessment

MediumTerminating active sessions forces application-layer transaction rollbacks

Expected OutputTotal connections drop safely below max_connections threshold in pg_stat_activity

Rollback Procedure:Reset temporary session timeouts, reload PgBouncer or revert pool sizing

PostgreSQL Docs: Connections

First 60 Seconds Emergency Protocol:

The error string is a symptom, not the root cause. Do not restart the server blindly. Run the diagnostic queries below to pinpoint the actual failure mode.

▸Symptom

Applications suddenly lose connectivity; server logs continuously report:

plaintext

FATAL: sorry, too many clients already

This error does not mean the PostgreSQL instance has crashed. According to the official PostgreSQL connection architecture, max_connections determines the maximum number of concurrent client connections (both active statements and idle sessions). Once this ceiling is saturated, the server rejects all subsequent TCP handshakes.

A vital engineering principle: "Too many clients" is not exclusively an idle connection leak; it is an absolute concurrency ceiling. In production, it stems from three distinct root patterns:

1Unpooled Client Leaks (`idle`): Microservice instances opening direct unpooled connections that remain dormant.
2Dangling Transactions (`idle in transaction`): Code opening transactions with BEGIN without issuing timely COMMIT or ROLLBACK.
3Active Concurrency Spikes (`active`): Slow lock-waiting queries piling up during traffic bursts, exhausting backend worker processes.

▸The Single Diagnostic Query

Connect via a superuser session and inspect connection distribution:

sql

SELECT count(*) AS total,
       count(*) FILTER (WHERE state = 'active')              AS active,
       count(*) FILTER (WHERE state = 'idle')                AS idle,
       count(*) FILTER (WHERE state = 'idle in transaction') AS idle_in_transaction
FROM pg_stat_activity;

SELECT usename, application_name, client_addr, count(*)
FROM pg_stat_activity
GROUP BY 1, 2, 3
ORDER BY 4 DESC
LIMIT 10;

Map your output to one of three root causes:

Finding	Root Cause	Solution
`idle` count > 60% of total, concentrated in one `application_name`	Unpooled connections: each pod/thread holds a dedicated socket	PgBouncer (transaction mode)
`idle_in_transaction` > 0 with long durations	App issues `BEGIN` without closing `COMMIT`	`idle_in_transaction_session_timeout` + code fix
`active` count near capacity, long execution times	True concurrency spike	Scale capacity + optimize slow queries

▸Step-by-Step Resolution

1. Verify thresholds.

sql

SHOW max_connections;
SHOW superuser_reserved_connections;

2. Terminate stale idle sessions (emergency triage).

sql

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

3. Set aggressive session timeouts.

sql

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

4. Deploy PgBouncer in transaction mode. Allows hundreds of app connections to share a small pool (e.g. 20-30) of database connections.

5. Enforce role-based connection limits.

sql

ALTER ROLE reporting_user CONNECTION LIMIT 10;

▸Permanent Prevention

Avoid bumping max_connections arbitrarily. Monitor throughput per backend rather than raw count.

•PostgreSQL First Restore Drill Runbook
•PostgreSQL psql CLI Reference
•Validated versions: PostgreSQL 14 / 15 / 16 / 17

Other Database Error Triage Playbooks

Other battle-tested diagnostic guides for high-severity database errors.

All Errors (20)

POSTGRESQL4 min