PgBouncer Too many open files: file descriptor exhaustion and refused connections

PgBouncer is logging Too many open files and clients are being turned away, or connections to PostgreSQL are failing with the same OS error. The confusing part: used_clients is nowhere near max_client_conn, the pools look healthy, and yet new connections are refused. The front door is not full. The kernel is out of file descriptors.

PgBouncer is FD-hungry by design. Every proxied connection consumes roughly two file descriptors, one for the client socket and one for the server socket, plus a baseline of listening sockets, admin console sockets, DNS resolver sockets, and the log file. When the process hits its Max open files limit, three things break at once: accept() on the listen socket fails so new clients cannot connect, new server connections to PostgreSQL cannot be opened so existing clients start queuing, and log writes can fail so diagnostics disappear exactly when you need them.

The other trap is timing. The FD limit is fixed at process start. You cannot raise it on a running PgBouncer. Every fix in this article ends with a restart, which drops all client and server connections, so plan the window accordingly.

What this means

The OS enforces a per-process ceiling on open file descriptors (rlimit NOFILE). When PgBouncer reaches it, the kernel returns EMFILE (“Too many open files”) on every syscall that allocates a descriptor: accept(), connect(), socket(), open(). PgBouncer has no queue for this condition. New clients are refused immediately, and new backend connections fail.

Two properties make this failure mode nastier than it looks:

1. The limit that matters is the process limit, not your shell’s. ulimit -n in your interactive shell tells you nothing about the running service. systemd units, PAM, and /etc/security/limits.conf each apply differently. The only authoritative source is /proc/<pid>/limits for the actual PgBouncer PID.
2. max_client_conn does not protect you. PgBouncer does not clamp that setting to the detected FD limit, and the process limit is fixed at start. If server connections and overhead consume more FDs than planned, you hit the kernel ceiling before the configured client limit. The signature is used_clients plateauing below max_client_conn while connections are refused.

flowchart TD
  A[Clients plus server connections
consume FDs] --> B[Process reaches
Max open files limit]
  B --> C[accept fails:
new clients refused]
  B --> D[connect fails:
no new server connections]
  B --> E[log writes may fail:
diagnostics lost]
  D --> F[cl_waiting grows,
query_wait_timeout fires]
  C --> G[used_clients plateaus
below max_client_conn]

Common causes

Quick checks

All of these are read-only and safe to run during an incident.

• Current FD usage vs limit. This is the single decisive check. If the count is at or near the limit, you have your answer.

# Count open FDs and read the process limit
PGBPID=$(pgrep -f pgbouncer | head -1)
ls /proc/$PGBPID/fd | wc -l
grep "Max open files" /proc/$PGBPID/limits

• The startup log line. At startup PgBouncer logs its kernel FD limit and its own estimate of maximum expected FD use. If the estimate exceeds the limit, the config was never valid.

# Find the FD line logged at process start
journalctl -u pgbouncer | grep -i "file descriptor"

• Client slots vs the configured limit. used_clients plateauing below max_client_conn while connections fail is the FD exhaustion signature, not a client-limit problem.

# Compare used client slots against the configured limit
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -Atc "SHOW LISTS;" | grep -E "used_clients|free_clients"
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -Atc "SHOW CONFIG;" | grep max_client_conn

• Log evidence. FD exhaustion, connection refusals, and accept failures are log-only signals. PgBouncer exposes no error counters via SHOW commands.

# Look for EMFILE and refusal messages
grep -iE "too many open files|no more connections allowed" /var/log/pgbouncer/pgbouncer.log | tail -20
journalctl -u pgbouncer --since "1 hour ago" | grep -i "too many open files"

• Effective systemd limit. The unit’s LimitNOFILE overrides anything your shell or limits.conf says.

# Show the unit and any drop-in overrides
systemctl cat pgbouncer

How to diagnose it

1. Confirm the ceiling is the kernel, not the config. Run the FD count vs limit check above. If FDs are within a few percent of Max open files, this is FD exhaustion. If FDs are nowhere near the limit and used_clients equals max_client_conn, you have the client-limit problem instead: see PgBouncer no more connections allowed (max_client_conn).
2. Check whose error it is. If “Too many open files” appears in the PostgreSQL log rather than PgBouncer’s, the backend is out of FDs. Each PostgreSQL backend opens many data files, bounded by max_files_per_process, and hundreds of PgBouncer server connections multiply into far more file handles than the backend limit allows. Check the postgres process /proc/<pid>/limits and current FD count the same way.
3. Reconstruct the budget. From SHOW LISTS and SHOW POOLS, total the client connections plus server connections (sv_active + sv_idle + sv_used + sv_tested + sv_login across pools), then add overhead for listen sockets, admin connections, DNS, and the log. Compare that total to the process limit. The official sizing formula is roughly max_client_conn + (max pool_size x total databases x total users) when each user connects under their own name, or max_client_conn + (max pool_size x total databases) when all users share one database user. Reserve at least 20% of the limit on top of that for non-connection FDs.
4. Find out why the limit is what it is. If /proc/PID/limits shows 1024 or 4096, the service was started without an explicit FD limit and inherited a default. If it shows a value that does not match your current config, the limit was changed after the process started and never took effect. The FD limit is fixed at process start; RELOAD does not change it.
5. Check for FD growth without pressure. If FDs climb over days under flat traffic, look for leaked client connections: SHOW CLIENTS sorted by connect_time will show very old idle connections holding sockets open. In session pooling mode, an idle client holds both a client FD and a server FD indefinitely.

Metrics and signals to monitor

Fixes

Raise the process FD limit

The correct mechanism depends on how PgBouncer is supervised. On systemd distros, use a drop-in override rather than editing the packaged unit file, which package updates overwrite:

# Create a drop-in override for the service
mkdir -p /etc/systemd/system/pgbouncer.service.d
cat > /etc/systemd/system/pgbouncer.service.d/override.conf <<'EOF'
[Service]
LimitNOFILE=64000
EOF
systemctl daemon-reload
systemctl restart pgbouncer

Size the limit from the budget formula above, not from a round number. A practical floor is max_client_conn x 2 + 500 to cover server connections and overhead, with 20% headroom on top. Also confirm both soft and hard limits: recent systemd defaults commonly start from DefaultLimitNOFILE=1024:524288, but distribution or manager configuration can change them. Use LimitNOFILE=SOFT:HARD when the hard limit also needs raising, and verify /proc/<pid>/limits afterwards.

Warning: the restart is mandatory and disruptive. The FD limit is fixed at process start, so a graceful reload does nothing here. The restart drops every client connection and every pooled server connection, and the pool cold-starts afterwards, with the first queries paying connection establishment latency. Do it in a maintenance window or behind a failover.

Verify afterwards:

# Confirm the new limit took effect
grep "Max open files" /proc/$(pgrep -f pgbouncer | head -1)/limits

Bring max_client_conn back inside FD headroom

If you cannot or do not want to raise the limit, reduce max_client_conn so the worst-case FD budget fits. Validate max_client_conn against the FD limit minus all non-client FD usage: server connections, listening sockets, the log file, pipe FDs, and admin sockets. A config that only works until the server side of the pool fills up is not a valid config.

Reap idle client connections

If FD growth comes from clients that connect and never disconnect, a lower max_client_conn is only a bandage. In transaction pooling mode, client_idle_timeout can reap idle frontend connections; in session pooling mode it does not apply to idle sessions holding server connections, so your options are switching pooling mode, fixing the application’s connection hygiene, or sizing for the FD cost. Identify offenders first with SHOW CLIENTS (old connect_time, no activity) before changing anything.

If PostgreSQL is the one out of FDs

Reduce the multiplier rather than only raising limits: lowering max_files_per_process reduces how many file handles each backend can hold open, and cutting PgBouncer’s total server connection count (smaller pool sizes, fewer pools) reduces how many backends exist. Also check the host-wide Linux ceiling (fs.file-max) if the aggregate across all processes is the constraint; it bounds total file handles kernel-wide, while max_files_per_process and each process rlimit bound one backend/process. There is no one-size-fits-all value—size from measured open-file counts and headroom.

Prevention

• Validate max_client_conn against the FD limit at every change. Any change to max_client_conn, pool sizes, database count, or user count changes the FD budget. Recompute it and compare against LimitNOFILE.
• Monitor FD usage as a first-class signal. Track /proc/PID/fd count against the process limit and alert at 80%. FD exhaustion is a hard wall; the trend line is the only warning you get.
• Alert on the log, not just SHOW output. “Too many open files” and “no more connections allowed” appear only in logs. A monitoring setup that scrapes only the admin console is blind to refusals.
• Watch client connection lifetime. Trend used_clients and the age distribution from SHOW CLIENTS. Slow growth under flat traffic is a leak, and it will eventually present as FD exhaustion.
• Check the startup log line after every restart. The kernel file descriptor limit ... max expected fd use message logged at each start is a free config validation.

How Netdata helps

• Netdata collects per-process file descriptor counts from /proc alongside the process limit, so FD saturation shows up as a trend approaching a known ceiling rather than a surprise at 3 a.m.
• It scrapes the PgBouncer admin console (SHOW POOLS, SHOW LISTS, SHOW STATS), so you can correlate used_clients plateauing below max_client_conn with the FD count hitting the limit, which is the exact signature that separates FD exhaustion from the client-limit failure.
• Pool-level signals (cl_waiting, maxwait, sv_active) on the same dashboard expose the secondary effect: server connections failing to open while FDs are exhausted, showing up as queue growth that looks like pool exhaustion but is not.
• Process uptime and restart detection explain sudden stat counter resets and help confirm whether the process died during the event.
• Long-term retention of FD usage and connection counts makes the slow-leak variant visible weeks before it becomes an incident.

Related guides

• PgBouncer max_client_conn tuning: setting the client limit against real FD headroom
• PgBouncer no more connections allowed (max_client_conn): the front door is full
• PgBouncer pool exhaustion: clients queue, wait times climb, and the retry cascade
• PgBouncer capacity planning: runway for pools, clients, and PostgreSQL slots
• PgBouncer monitoring checklist: the signals every connection pooler needs
• How PgBouncer actually works in production: a mental model for operators
• PgBouncer avg_wait_time high: the latency the pool itself is injecting
• PgBouncer maxwait high: the oldest client waiter and how close it is to timing out
• PgBouncer pool utilization high: sv_active approaching pool_size before clients queue
• PgBouncer monitoring maturity model: from survival to expert
• PgBouncer LISTEN/NOTIFY not working: why pub/sub needs session pooling
• PgBouncer advisory locks in transaction mode: orphaned locks and mysterious contention