PHP-FPM max_children Reached

PHP-FPM max_children Reached

The PHP-FPM error "server reached pm.max_children setting" means your PHP pool has hit its maximum process limit and cannot spawn more workers to handle incoming requests. New requests are queued and eventually time out, causing users to see 502 or 504 errors from nginx. This is one of the most common high-traffic PHP performance problems and usually means either the max_children value is too low for the load, or PHP processes are being held open longer than expected (slow database queries, blocking I/O).

What this error means

PHP-FPM process lifecycle:

  nginx request → PHP-FPM socket → available worker?

  YES: worker handles request (typical: 50-500ms)
       worker returns to pool after request completes

  NO (max_children reached):
       request queued → waits for a free worker
       if queue full → 502/504 returned to user

  max_children = 50, but each request takes 2 seconds:
    50 workers / 2 seconds = only 25 req/sec capacity
    If traffic = 100 req/sec → workers exhausted immediately

Immediate response

# Check PHP-FPM error log immediately:
sudo tail -50 /var/log/php8.1-fpm.log

PHP-FPM log showing max_children

[09-Jun-2025 14:30:45] WARNING: [pool www] server reached pm.max_children setting (50),
consider raising it
[09-Jun-2025 14:30:46] WARNING: [pool www] seems busy (you may need to increase pm.start_servers,
or pm.min/max_spare_servers), spawning 8 children, there are 0 idle, and 47 total children

# Check current PHP-FPM status (if status page enabled in pool config):
sudo curl http://127.0.0.1/php-fpm-status?full

# Check process count in real time:
watch -n 1 'ps aux | grep php-fpm | grep -v grep | wc -l'

# See how long PHP processes have been running (stuck processes = slow backend):
ps aux | grep php-fpm | awk '{print $10, $11}' | sort -rn | head -10

Tuning PHP-FPM pool settings

sudo nano /etc/php/8.1/fpm/pool.d/www.conf

/etc/php/8.1/fpm/pool.d/www.conf — tuning pm settings

; Process manager:
pm = dynamic

; Calculate max_children based on available RAM:
; max_children = (Available RAM for PHP) / (Memory per process)
; Memory per process: check with: ps --no-headers -o "rss,cmd" -C php-fpm8.1 | awk '{sum+=$1} END {print sum/NR/1024 "MB"}'
; Example: 4GB server, 500MB for OS, 500MB MySQL = 3GB for PHP
;          Each PHP process uses 50MB → max_children = 60
pm.max_children = 60

; Number of children to start at boot:
pm.start_servers = 10

; Minimum spare (idle) processes:
pm.min_spare_servers = 5

; Maximum spare (idle) processes:
pm.max_spare_servers = 20

; Recycle workers after N requests (prevents memory leaks):
pm.max_requests = 500

; Request timeout (kill stuck processes):
request_terminate_timeout = 30s

# Apply changes:
sudo systemctl reload php8.1-fpm

# Enable the status page for monitoring:
# In www.conf: pm.status_path = /php-fpm-status

Root causes and long-term fixes

# Find slow PHP processes (running > 5 seconds = stuck):
ps aux | grep php-fpm | awk '$10 > "0:05" {print $0}'

# Check if PHP processes are waiting for MySQL:
sudo strace -p PHP_PID -e trace=network 2>&1 | head -20
# If you see recv() waiting = PHP blocked on MySQL

# Enable PHP-FPM slow log to find slow requests:
sudo nano /etc/php/8.1/fpm/pool.d/www.conf
# slowlog = /var/log/php8.1-fpm-slow.log
# request_slowlog_timeout = 5s
sudo systemctl reload php8.1-fpm
sudo tail -f /var/log/php8.1-fpm-slow.log
# Shows PHP stack trace for requests taking > 5 seconds

Conclusion

Calculate pm.max_children from available RAM divided by average PHP process size, not by guessing. Set it too high and PHP-FPM will exhaust server memory, causing OOM kills and total server failure. Set it too low and requests queue up during traffic spikes. The request_terminate_timeout = 30s setting is a safety valve — it kills PHP processes stuck for more than 30 seconds, freeing workers for new requests when a backend dependency (MySQL, Redis, API) becomes slow.