PHP-FPM: server reached pm.max_children – what to do
In short
The warning means that every PHP-FPM worker of a pool was busy and new requests had to wait in the listen queue. Work out how much memory one worker really uses, divide the memory you can spare for PHP by that figure, and set pm.max_children to the result. If workers are busy because requests are slow, fix the slow requests first, because a larger pool only moves the bottleneck.
The message server reached pm.max_children setting means that all worker processes of a PHP-FPM pool were busy at once and the next request had to wait. The fix has two parts: find out whether the workers are busy for a good reason (real traffic) or a bad one (slow requests), and then set pm.max_children to a value that the memory of the server can actually carry. This article shows how to do both.
What does the warning mean exactly?
PHP-FPM runs one or more pools. Each pool has a fixed upper limit of worker processes, and each worker handles exactly one request at a time. When the limit is reached, PHP-FPM writes a line like this to its log:
[18-Nov-2026 09:14:02] WARNING: [pool www] server reached pm.max_children setting (5), consider raising itOn Debian and Ubuntu the log is /var/log/php8.3-fpm.log (with your PHP version in the name), on the RHEL family /var/log/php-fpm/error.log. Count how often it happens:
grep -c "reached pm.max_children" /var/log/php8.3-fpm.logRequests that find no free worker are not dropped immediately. They wait in the listen queue of the socket. If a worker becomes free in time, the visitor only sees a slower page. If not, the web server gives up and answers with 502 Bad Gateway or 504 Gateway Timeout. A single warning during a traffic peak is harmless. A warning every few minutes is a capacity problem.
The value in brackets is the current limit. The 5 above is the default that Debian and Ubuntu ship in /etc/php/8.3/fpm/pool.d/www.conf, and it is too low for almost any real site. On the RHEL family the service is called php-fpm and the pool file is /etc/php-fpm.d/www.conf; the directives are the same.
How do I see what the pool is doing right now?
PHP-FPM has a built-in status page. Enable it in the pool configuration:
; /etc/php/8.3/fpm/pool.d/www.conf
pm.status_path = /fpm-statusReload the service with systemctl reload php8.3-fpm. The status page must never be public. Either allow the path only for 127.0.0.1 in the web server, or query the socket directly without going through the web server at all:
apt install libfcgi-bin
SCRIPT_NAME=/fpm-status SCRIPT_FILENAME=/fpm-status REQUEST_METHOD=GET \
cgi-fcgi -bind -connect /run/php/php8.3-fpm.sockThe output looks like this:
pool: www
process manager: dynamic
start time: 18/Nov/2026:08:01:30 +0000
start since: 4352
accepted conn: 18230
listen queue: 0
max listen queue: 14
listen queue len: 4096
idle processes: 2
active processes: 3
total processes: 5
max active processes: 5
max children reached: 7
slow requests: 0The lines that matter:
active processesis the number of workers serving a request at this moment.listen queueis the number of requests waiting for a worker right now. Anything that stays above zero means visitors are waiting.max listen queueis the highest queue length since the start of PHP-FPM.max children reachedcounts how often the pool hit its limit since the start.
Note that the status page does not show pm.max_children itself. total processes is the current size of the pool, not the permitted size. You get the configured values with php-fpm8.3 -tt.
How do I calculate pm.max_children?
The limit is a memory question. Each worker is a full PHP process, and all workers together must fit into RAM alongside everything else on the server.
First measure what a worker uses. This command averages the resident memory of all running PHP-FPM processes:
ps --no-headers -o rss -C php-fpm8.3 | awk '{s+=$1} END {printf "%d processes, average %.0f MB\n", NR, s/NR/1024}'12 processes, average 78 MBMeasure under normal load, not right after a restart, because workers grow as they handle requests. The figure is an upper estimate: resident memory includes shared memory such as the OPcache, which exists only once. That errs on the safe side, which is what you want here.
Then decide how much memory PHP may use. Take the total RAM and subtract what the database, the web server, other services and the file cache of the kernel need. On a server with 8 GB RAM and a local database that uses 2.5 GB, about 4 GB for PHP is a reasonable budget.
pm.max_children = memory for PHP / memory per worker
= 4096 MB / 78 MB
= 52 (rounded down to 50)If several pools run on the server, the budget is shared between them: the sum of all pm.max_children values is what counts.
Which pm settings belong together?
A typical configuration for the example above:
pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 15
pm.max_requests = 500pm = dynamickeeps betweenmin_spare_serversandmax_spare_serversidle workers ready and starts more as needed, up tomax_children.pm = staticalways runs exactlymax_childrenworkers. No start-up cost, constant memory use. Useful on dedicated PHP servers.pm = ondemandstarts workers only when requests arrive and stops them afterpm.process_idle_timeout. Good for servers with many small, rarely used pools.pm.max_requestsrestarts a worker after that many requests. This limits the effect of memory leaks in extensions or application code. The default is0, meaning never.
Check the syntax before reloading, so that a typing error does not take the site down:
php-fpm8.3 -t
systemctl reload php8.3-fpmWhat if the workers are busy because requests are slow?
A pool also fills up when each request takes too long. Fifty workers that each wait three seconds for a database query handle fewer requests than ten fast ones. Raising the limit in that situation increases the pressure on the database and makes things worse.
The slow log of PHP-FPM shows where the time goes. It writes a stack trace for every request that runs longer than the threshold:
request_slowlog_timeout = 5s
slowlog = /var/log/php8.3-fpm.slow.logTypical causes are slow database queries, calls to external APIs without a timeout, and bots that request expensive pages in bulk. For API calls and similar, set a hard limit with request_terminate_timeout so that a hanging request cannot hold a worker forever. Be careful with this setting if you run long jobs through the web server, because it ends those as well.
To judge whether the server as a whole is overloaded or just the pool is too small, look at the load in relation to the CPU cores, as described in Linux load average explained.
Common mistakes
- Raising the value without measuring memory. A limit of 200 with 80 MB per worker needs 16 GB in the worst case. If the server has less, it starts swapping under load or the kernel ends processes, often the database.
- Editing the wrong file. Each PHP version has its own configuration directory, and each pool its own file. Check with
php-fpm8.3 -ttwhich values are active. - Forgetting the web server. If Apache or nginx accept far more simultaneous connections than PHP-FPM has workers, the queue fills up. If they accept fewer, the extra workers are never used.
- Leaving the status page open to the internet. It reveals internal details and, in its full view, the URLs currently being processed.
- Treating a filled pool as a PHP problem only. A full disk or a blocked database produces the same symptom. If the pool fills up suddenly, check the basics as well, for example with the steps in Linux disk full: find what is using the space.
Checklist
- Count the warnings in the PHP-FPM log and note when they occur.
- Enable the status page for local access only and read
listen queueandmax children reached. - Measure the average memory per worker under normal load.
- Set a memory budget for PHP and divide it by the memory per worker.
- Set
pm.max_childrenand the matching spare values, test withphp-fpm8.3 -t, reload. - Enable the slow log and fix the slowest requests.
- Watch the queue and the memory for a few days and adjust.
How Lynx Heartbeat helps
The Lynx Heartbeat agent reads the PHP-FPM status page locally every minute and records the active processes, the length of the listen queue and whether the pool reached its limit since the last measurement. You therefore see the moment the pool fills up, next to load and memory of the same server, instead of finding the warning in a log file days later. Alerts are debounced, so one short peak does not wake anyone; how that works is described in alert fatigue, quiet hours and escalation. An overview of what the agent measures is on the features page.
Frequently asked questions
What does 'server reached pm.max_children setting' mean?
All worker processes of the PHP-FPM pool were busy at the same moment. Further requests are not rejected at once, they wait in the listen queue of the socket until a worker is free. Visitors notice this as slow pages or, if the wait is too long, as 502 or 504 errors from the web server.
How do I calculate pm.max_children?
Divide the memory you can reserve for PHP by the memory one worker uses. Measure the average resident memory of the running workers with ps, add a safety margin, and leave enough memory for the database, the web server and the file cache. Example: 4 GB for PHP and 80 MB per worker give about 50 children.
Which is better: pm = dynamic, static or ondemand?
dynamic is a sound default for most servers. static avoids the cost of starting processes and suits dedicated PHP servers with steady traffic. ondemand starts workers only when requests arrive and saves memory on servers with many rarely used pools, at the price of a slower first request.
Does raising pm.max_children make my site faster?
Only if requests were actually waiting for a free worker and the server has free memory and CPU. If workers are busy because of slow database queries or external calls, more workers put more load on the same bottleneck. Too high a value can push the server into swap or trigger the OOM killer.