PHP-FPM "server reached pm.max_children setting (N), consider raising it"

The warning appears in your PHP-FPM error log verbatim:

WARNING: [pool www] server reached pm.max_children setting (5), consider raising it

The pool tried to fork another worker and hit the configured ceiling. Each occurrence is a request that had to wait for a worker to free up instead of being served immediately. The line is emitted at warning level. Setting log_level = error hides it, but that also hides every other warning; PHP-FPM has no per-message suppression directive.

The number in parentheses is your current pm.max_children. The upstream default in www.conf is 5, which is too low for almost any modern workload. Before you raise it, confirm worker exhaustion is the actual failure mode and that memory headroom exists. Blindly increasing pm.max_children without checking RAM is the most common path from “slow site” to OOM death spiral.

This article covers what the warning means in each process manager mode, how to confirm the cause, how to size the limit safely, and what to fix first when the real problem is upstream of PHP-FPM.

What this means

The master process maintains a scoreboard of workers. In dynamic and ondemand modes, when demand rises and the process manager wants to spawn an additional worker, it checks against pm.max_children. If the current count is at the ceiling, it refuses to fork, increments the internal counter, and emits the warning. The request then either waits for an idle worker or, if the listen backlog fills, gets dropped at the kernel level.

Three things make this warning easy to misread:

1. It is a counter, not a rate. The max children reached field on the status page is cumulative since the last restart. A large absolute number from an incident three days ago is harmless. What matters is whether it is incrementing right now, during normal traffic.
2. It is meaningless in static mode. With pm = static, all workers are pre-forked at startup. The process manager never attempts to spawn beyond the configured count, so the counter stays at zero. The equivalent signal in static mode is listen-queue growth.
3. The warning does not tell you why workers are busy. Workers can be saturated from genuine traffic, a slow database query holding them hostage, or a memory leak reducing the effective pool. Raising pm.max_children fixes only the first case.

The failure cascade, once saturation begins, is steep:

flowchart TD
    A[Traffic arrives] --> B{Idle workers available?}
    B -- Yes --> C[Serve immediately]
    B -- No --> D[max_children reached increments]
    D --> E[Request enters socket backlog]
    E --> F{Backlog full?}
    F -- No --> G[Request waits, latency rises]
    F -- Yes --> H[Kernel drops connection]
    H --> I[Web server returns 502]

The transition from “all requests served immediately” to “excess requests queue” is instantaneous. There is no graceful degradation in a one-request-per-worker model. The listen backlog provides a short buffer, then connections are refused.

Common causes

Quick checks

Run these read-only. They confirm whether you are hitting the ceiling and give the first hint at why.

# Confirm the counter is incrementing now, not just historically
curl -s http://127.0.0.1/fpm-status | grep "^max children reached"
# Wait 60 seconds, poll again. A delta means active saturation.

# Current worker utilization
curl -s http://127.0.0.1/fpm-status | grep -E "^(active|idle|total) processes"

# Listen queue depth and configured maximum
curl -s http://127.0.0.1/fpm-status | grep -E "^listen queue"

# Which process manager mode is in effect
php-fpm -tt 2>&1 | grep -E "^pm "

# Per-worker memory (RSS is inflated by shared opcache pages)
ps -eo pid,rss,cmd | grep '[p]hp-fpm' | grep -v master | awk '{sum+=$2; count++} END {print sum/count " KB avg, " count " workers"}'

# Accurate per-process memory accounting via PSS
smem -P php-fpm -c 'pid pss rss' -s pss 2>/dev/null | tail -n +2 | awk '{sum+=$2; count++} END {print sum/count " KB avg PSS, " count " workers"}'

# Slow log: the most direct signal of WHY workers are stuck
tail -50 /var/log/php-fpm/slow.log 2>/dev/null || echo "slow log not configured or empty"

# Recent worker crashes (signals 11 or 7 indicate extension bugs, not capacity)
grep -c "SIGSEGV\|SIGBUS\|signal 11\|signal 7" /var/log/php-fpm/error.log 2>/dev/null

# Kernel-level OOM kills targeting php-fpm
dmesg | grep -i "oom.*php" 2>/dev/null | tail -10

The slow log is the single most important signal here. If request_slowlog_timeout is 0 (the default, meaning disabled), you have no visibility into which code path is tying up workers. Enable it. A value of 5 seconds is a reasonable starting point.

How to diagnose it

1. Confirm active saturation, not historical noise. Poll max children reached twice, 60 seconds apart. Flat counter means the warning was from a past event. A climbing counter means an active problem.
2. Check the process manager mode. The warning is only meaningful in dynamic and ondemand. In static, ignore it and look at the listen queue instead.
3. Correlate active processes with max_children. Active count equals max_children with zero idle means the pool is at capacity. Active well below max_children with the counter incrementing points elsewhere: spawn failure from memory pressure or permissions.
4. Read the slow log before changing anything. If workers are blocked on database calls, external APIs, or session locks, raising max_children will not help. New workers hit the same slow code path and drain too. The slow log stack trace tells you whether the problem is capacity or a stuck dependency.
5. Check memory headroom before considering a raise. This is the step most teams skip, and it prevents the OOM spiral.
6. Rule out a crash loop. If workers are dying faster than they are being replaced, the effective pool is smaller than configured. Check the error log for exited on signal entries and dmesg for OOM kills.

Metrics and signals to monitor

Fixes

If the pool is genuinely undersized

First, calculate the memory-safe ceiling:

memory_safe_max_children = (total_RAM * 0.7 - OS_overhead) / avg_worker_RSS

Use PSS, not RSS, for the per-worker figure. RSS is inflated by shared opcache pages counted in every worker, which overestimates unique memory by 30 to 50 percent. A worker reporting 60 MB RSS might have a PSS of 35 MB.

Example: a host with 8 GB RAM, 1 GB reserved for the OS and other services, and an average worker PSS of 40 MB gives a safe ceiling of roughly (8192 * 0.7 - 1024) / 40 = 117. If your current max_children is 50 and you are saturating, you have room to raise it. If your current value is already 150, raising it further will drive you into swap and OOM.

To apply the change, edit the pool config and reload:

# Edit /etc/php/<version>/fpm/pool.d/www.conf (path varies by distro)
# pm.max_children = <new_value>

# Graceful reload (brief interruption: workers drain before master re-execs)
kill -USR2 $(cat /run/php-fpm.pid 2>/dev/null || cat /run/php/php*-fpm.pid)

SIGUSR2 is the graceful reload signal. Unlike nginx, PHP-FPM drains old workers before spawning new ones, so there is a brief window with reduced or zero capacity. Do this during a low-traffic window if possible.

If a slow dependency is the real cause

This is the most common scenario behind the warning. Workers are busy because each request takes seconds instead of milliseconds, usually waiting on a database, an external API, or a session file lock.

Raising max_children here is a temporary bandage. New workers hit the same slow code. The fixes are upstream of PHP-FPM:

• Slow database query: check the slow query log, add the missing index, or fix the lock contention.
• External API timeout: set an explicit, shorter timeout in application code. PHP cURL defaults can be very high.
• Session lock contention: call session_write_close() early in long-running requests, or switch to Redis or Memcached session handling.
• Blocked NFS or DNS: check mount health and resolver behavior.

To kill a stuck worker during an incident:

# Graceful: finishes current request then exits (does NOT interrupt in-flight work)
kill -SIGQUIT <worker_pid>

If a memory leak is reducing effective capacity

If per-worker RSS is climbing monotonically and pm.max_requests is 0 or unset, workers never recycle. The leak accumulates until the OOM killer fires, taking out workers or the master. Restarting fixes it temporarily, but it recurs.

Set pm.max_requests to a finite value, typically 500 to 1000:

pm.max_requests = 500

This forces periodic worker recycling. The cost is a fork every 500 requests, which is negligible. The benefit is bounded memory growth. After setting it, reload FPM to reset all workers to baseline memory.

If you are in static mode

The warning is meaningless in static mode because the process manager never attempts to spawn beyond the pre-forked count. If you see saturation symptoms in static mode, watch the listen queue. Raising max_children in static mode requires a full restart, not just a reload, because workers are forked at startup.

Prevention

• Poll the status page at 1-second intervals for operational alerting. Saturation events unfold in seconds. A 10-second poll interval will miss the critical first moments of a dependency-induced drain. Track the rate of change of max children reached, not the absolute counter.
• Enable the slow log on every production pool. request_slowlog_timeout = 5 is a safe starting point. Without it, you know workers are busy but not why.
• Set pm.max_requests to 500 or 1000. This is the primary defense against unbounded memory growth from leaks you have not found yet.
• Set request_terminate_timeout to a finite value so a single stuck request cannot hold a worker forever.
• Size max_children from measured PSS, not from CPU cores. PHP-FPM workers spend most of their time waiting on I/O. A 4-core machine can run 50 to 200 workers if memory allows.
• Monitor both sides. The FPM status page gives the internal view. The web server error log plus kernel ListenOverflows give the external view. When the backlog overflows, the kernel drops connections that FPM never sees.
• Track capacity runway. If peak active count is at 80 percent of max_children and growing 15 percent month over month, you have roughly one month before hitting the wall. Plan the raise before the warning appears.

How Netdata helps

• Per-second polling of the FPM status page captures the max children reached rate of change that 10-second intervals miss. The counter resets on restart, so a continuous rate view is more useful than the raw cumulative value.
• Correlation of active processes, idle processes, and listen queue on a single timeline confirms worker exhaustion in one glance instead of three separate commands.
• Per-worker RSS trending over hours and days makes memory leaks visible before they become OOM events.
• Slow log and error log integration surfaces the blocking function or crashing worker alongside the saturation metrics, so you can distinguish “too much traffic” from “stuck dependency” without switching tools.
• Kernel-level socket monitoring catches the connection drops that the FPM status page cannot see, closing the blind spot between worker saturation and user-facing 502s.
• Composite alerts combining “active equals max_children” with “listen queue greater than zero for more than 60 seconds” reduce noise from brief bursts that self-resolve; configure this as a user-level composite alert rather than assuming it is built in.

Related guides

• How PHP-FPM actually works in production: a mental model for operators
• PHP-FPM monitoring checklist: the signals every production pool needs
• PHP-FPM monitoring maturity model: from survival to expert
• PHP-FPM worker exhaustion: all workers busy and requests piling into the backlog