When the PHP-FPM pool saturates, the socket backlog is the buffer between “requests are waiting” and “requests are dropped.” Operators who hit 502 storms often reach for listen.backlog first, bump it to a large number, reload PHP-FPM, and see no change. The reason is almost always one of two things: the kernel silently clamped the request to net.core.somaxconn, or the backlog was never the bottleneck.
The short version: a larger backlog only lengthens the queue. It buys a few seconds of burst absorption. It never fixes a worker pool that cannot keep up.
What it is and why it matters
listen.backlog is the size of the listen queue PHP-FPM asks the kernel to allocate for the pool’s listening socket (Unix or TCP). When the web server opens a FastCGI connection, the kernel places it in this queue until an idle PHP-FPM worker accepts it from the shared listening socket. If the queue is full when a new connection arrives, the kernel drops it. The web server sees a connection failure and returns 502.
Two things make this setting a frequent source of confusion.
First, the value PHP-FPM requests is not necessarily the value the kernel grants. net.core.somaxconn is a system-wide cap. The effective backlog is the minimum of the requested value and somaxconn. Setting listen.backlog = 65535 on a host where somaxconn = 128 yields an effective backlog of 128, with no warning.
Second, the default changed across PHP versions. PHP releases before 8.2 default to 511 on Linux. PHP 8.2 and later default to -1, which tells the kernel to use somaxconn directly (typically 4096 on modern Linux). The php-src code is authoritative for the boundary: the Linux default is 511 through PHP 8.1 and -1 from PHP 8.2.
Because of the version shift, tuning recipes written for PHP 7.4 may have no effect on PHP 8.3, and vice versa.
How it works
The application (PHP-FPM) passes a requested backlog to the listen(2) syscall. The kernel caps it to somaxconn. The result is the queue depth the kernel will actually honor.
flowchart TD
A["listen.backlog in pool config"] --> B{"PHP version on Linux"}
B -->|"PHP <= 8.1"| C["Requests 511"]
B -->|"PHP 8.2+"| D["Requests -1"]
D --> E["Means: use somaxconn"]
C --> F["Kernel clamps to min(requested, somaxconn)"]
E --> F
F --> G["Effective backlog"]
G --> H{"Arrival rate > accept rate?"}
H -->|"No"| I["Queue stays empty"]
H -->|"Yes"| J["Queue fills"]
J -->|"Full"| K["Kernel drops new connections"]
K --> L["ListenOverflows increments"]
L --> M["Web server: 502, FPM unaware"]Version defaults at a glance
| PHP version | listen.backlog default on Linux | Effective behavior |
|---|---|---|
| PHP 7.x, 8.0, 8.1 | 511 | Capped at min(511, somaxconn) |
| PHP 8.2 and later | -1 | Resolves to somaxconn (typically 4096) |
On PHP 8.2+, if somaxconn is 4096, the effective backlog is 4096 without any explicit configuration. On older PHP, even with somaxconn at 4096, the effective backlog is still 511 because PHP asked for 511. To get the larger value on older PHP, set listen.backlog = -1 or a specific number in the pool config.
The kernel clamp
The clamp is silent. There is no log line, no error, no warning. The only way to confirm what the kernel actually granted is to inspect the socket with ss or read the kernel counters.
# Check the system-wide cap
sysctl net.core.somaxconn
# Inspect the listening socket (Recv-Q is current depth, Send-Q is the effective backlog)
ss -xlnp | grep php
ss -tlnp | grep 9000
On the LISTEN line, Send-Q shows the effective backlog the kernel honored, and Recv-Q shows the current number of connections waiting to be accepted. If Send-Q is far smaller than the listen.backlog you configured, the kernel clamped it.
Modern versus legacy somaxconn
On kernel 5.x and later, net.core.somaxconn defaults to 4096. Older distributions (RHEL/CentOS 7, Ubuntu 18.04 era) shipped with 128. A host provisioned years ago and never re-tuned may still carry the old default, silently capping even a PHP 8.2+ pool to a 128-deep queue. Linux raised this default from 128 to 4096 in kernel 5.4.
Where it shows up in production
The PHP-FPM status page exposes three relevant fields:
listen queue: current number of connections waiting.max listen queue: high water mark since pool start.listen queue len: the configured maximum (the effective backlog).
Two reporting traps apply.
The Unix socket status page bug
On Unix sockets, the status page often reports listen queue and listen queue len as 0 even when the kernel queue is non-empty. This is a known cosmetic issue (PHP Bug #80739). The queue is real and functional; the counter is wrong.
Switching the pool to TCP makes the status page counter work, but TCP adds overhead and is not recommended purely to fix a reporting bug. Use ss to observe the real depth:
# Recv-Q on the LISTEN line is the real current depth
ss -xlnp | grep php
Kernel drop counters
When the backlog fills, the kernel drops new connections before PHP-FPM ever sees them. PHP-FPM has no instrumentation for these drops. The signal lives in the kernel:
# Cumulative counters since boot
nstat -az | grep -i listen
# TcpExtListenOverflows and TcpExtListenDrops are the relevant fields
# Or via /proc
grep -E 'ListenOverflows|ListenDrops' /proc/net/netstat
A non-zero and growing ListenOverflows count on the PHP-FPM host is direct evidence that the backlog overflowed. This is the signal that distinguishes “502s from backlog overflow” from a dead master or a socket permission problem.
Tradeoffs and when to use it
A larger backlog only lengthens the queue. It does not add workers, it does not make requests faster, and it does not increase throughput. If the worker pool is saturated because requests are slow or traffic is above provisioned capacity, a bigger backlog just delays the 502s by a few seconds.
When raising somaxconn is correct
Raise net.core.somaxconn only when you have evidence that the effective backlog is being clamped below what you intend, and you have a legitimate burst-absorption case.
# WARNING: this overwrites any existing file at this path. Check first.
echo 'net.core.somaxconn = 8192' > /etc/sysctl.d/99-php-fpm.conf
sysctl -p /etc/sysctl.d/99-php-fpm.conf
Then verify the effective backlog with ss. On PHP 8.2+ this takes effect after a PHP-FPM restart (see the restart caveat below). On older PHP, you must also set listen.backlog explicitly, otherwise PHP still asks for 511.
When raising listen.backlog is correct
On PHP 8.2+, you almost never need to set listen.backlog explicitly. The default of -1 already resolves to somaxconn. Setting it to a specific number is only useful if you want a backlog smaller than somaxconn, which is rare.
On PHP < 8.2, setting listen.backlog = -1 (or a specific large number) is a legitimate fix if you have confirmed via ss that the effective backlog is 511 and you have a burst pattern that 511 cannot absorb.
In both cases, the prerequisite is the same: you have confirmed the worker pool is correctly sized and the saturation is a genuine transient burst, not a chronic throughput deficit.
Restart, not reload
Changing listen.backlog requires a full PHP-FPM restart, not a graceful reload (SIGUSR2). The listening socket is created at master startup. A reload re-reads configuration but does not recreate the socket, so the old backlog stays in effect.
# Causes a brief outage. Plan it.
systemctl restart php-fpm
The real fixes
When the backlog is overflowing regularly, the backlog is a symptom, not the problem. The fixes, in order of impact:
- Reduce per-request latency. The slow log (
request_slowlog_timeout) is the fastest path to identifying what is blocking workers. A worker that takes 5 seconds instead of 50ms ties up a slot 100 times longer. - Increase
pm.max_children, but only after checking memory:avg_worker_RSS * max_children + OS_overheadmust fit in available RAM. Blindly raising it causes the OOM death spiral. - Address slow upstream dependencies (database, external APIs) that are poisoning workers and holding slots open.
- For chronic capacity shortfalls, add hosts or move to a long-lived PHP runtime that does not reinitialize the interpreter per request.
Raising the backlog is item zero: a few seconds of borrowed time while you do the real work.
File descriptor limits
A secondary cap: systemd’s LimitNOFILE or the process ulimit -n can prevent the kernel from allocating a large queue. If you raise somaxconn to 8192 but the PHP-FPM unit has LimitNOFILE=1024, the effective queue may still be constrained. Check the master’s actual limit:
# Per-process FD limit
cat /proc/$(pgrep -f 'php-fpm: master')/limits | grep "Max open files"
Raise it in the systemd override if needed.
Signals to watch in production
| Signal | Why it matters | Warning sign |
|---|---|---|
listen queue (status page) | Direct view of requests waiting for a worker | Sustained non-zero value means workers cannot keep up |
max listen queue (status page) | High water mark since pool start | Non-zero when you did not expect queuing means a past saturation event |
ss Recv-Q on the LISTEN socket | Real queue depth (works around the Unix socket reporting bug) | Growing Recv-Q while status page shows 0 |
ss Send-Q on the LISTEN socket | The effective backlog the kernel granted | Far below configured listen.backlog means the kernel clamped it |
TcpExtListenOverflows (kernel) | Connections dropped because the backlog was full | Any non-zero rate during traffic means users got 502s |
active processes / pm.max_children | Worker utilization ratio | Sustained at 100% is the precondition for backlog growth |
| Web server 502 rate | The user-facing symptom of backlog overflow | Spike correlates with ListenOverflows increments |
Correlating these is what separates “the backlog is too small” from “the backlog is full because the pool is saturated.” The first is a tuning problem. The second is a capacity problem. Only the first is fixed by raising the backlog.
How Netdata helps
- Per-second polling of the PHP-FPM status page surfaces
listen queue,max listen queue, andlisten queue lenwithout the 10-to-30-second polling gaps that miss transient saturation events. - Kernel socket metrics (
ss-equivalent depth,ListenOverflows,ListenDrops) are collected alongside the FPM status, making drops that the FPM status page cannot report visible on the same timeline. - Worker utilization (
active processes,idle processes,max children reached) is charted alongside the listen queue, making the saturation precondition visible at a glance. - Web server upstream error metrics (nginx/Apache 502 and 504 rates) are correlated with FPM signals, so a backlog overflow shows up as a coordinated signal across both layers.
Related guides
- PHP-FPM 502 Bad Gateway: the web server cannot reach the pool
- PHP-FPM 504 Gateway Timeout: requests accepted but never finishing in time
- PHP-FPM active processes near max_children: reading pool utilization
- PHP-FPM in containers: cgroup limits and the silent OOM kill
- PHP-FPM “child N exited on signal 11 (SIGSEGV)”: worker segfaults
- PHP-FPM “connect() failed (111: Connection refused) while connecting to upstream”
- PHP-FPM crash loop and fork storm: workers dying faster than they serve
- PHP-FPM dynamic mode scaling lag: why the pool cannot keep up with bursts
- PHP-FPM emergency restart: “failed processes threshold reached, initiating reload”
- PHP-FPM graceful reload: the brief no-worker window on SIGUSR2
- How PHP-FPM actually works in production: a mental model for operators
- PHP-FPM idle processes at zero: no burst headroom left