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 the PHP-FPM master accepts it and hands it to an idle worker. 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).

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"}
  B -->|"PHP < 8.2 on Linux"| C["Requests 511"]
  B -->|"PHP 8.2+ on Linux"| 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 versionlisten.backlog default on LinuxEffective behavior
PHP 7.x, 8.0, 8.1511Capped at min(511, somaxconn)
PHP 8.2 and later-1Resolves 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.

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:

  1. 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.
  2. Increase pm.max_children, but only after checking memory: avg_worker_RSS * max_children + OS_overhead must fit in available RAM. Blindly raising it causes the OOM death spiral.
  3. Address slow upstream dependencies (database, external APIs) that are poisoning workers and holding slots open.
  4. 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

SignalWhy it mattersWarning sign
listen queue (status page)Direct view of requests waiting for a workerSustained non-zero value means workers cannot keep up
max listen queue (status page)High water mark since pool startNon-zero when you did not expect queuing means a past saturation event
ss Recv-Q on the LISTEN socketReal queue depth (works around the Unix socket reporting bug)Growing Recv-Q while status page shows 0
ss Send-Q on the LISTEN socketThe effective backlog the kernel grantedFar below configured listen.backlog means the kernel clamped it
TcpExtListenOverflows (kernel)Connections dropped because the backlog was fullAny non-zero rate during traffic means users got 502s
active processes / pm.max_childrenWorker utilization ratioSustained at 100% is the precondition for backlog growth
Web server 502 rateThe user-facing symptom of backlog overflowSpike 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, and listen queue len without 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.