server reached pm.max_children setting means every PHP-FPM child in the pool is busy and FPM won’t start another. New requests wait in the socket’s backlog. If they wait too long, nginx returns a 502 or 504. Raising the number fixes the warning, until the pod runs out of memory.
What breaks at peak
Each PHP-FPM child serves one request at a time. pm.max_children caps the children in a pool, and the stock www.conf ships with 5. When a sixth request arrives while five are busy, FPM logs a warning like this, then appends advice to raise the setting:
[20-Nov-2026 14:02:11] WARNING: [pool www] server reached pm.max_children setting (5)
With pm = ondemand the line reads server reached max_children setting, without the pm. prefix. With pm = dynamic, a pool short on idle children logs another warning first:
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 12 total children
With pm = static, FPM logs neither warning, even when every child is busy. You only see the result in nginx’s error log. A full listen backlog on a Unix socket gives this:
connect() to unix:/run/php/php-fpm.sock failed (11: Resource temporarily unavailable) while connecting to upstream
A request that sat in the queue and then ran slow gives this, and the client gets a 504:
upstream timed out (110: Connection timed out) while reading response header from upstream
The usual cause is a slow dependency. Children wait on a database query or an API call, so they stay busy longer, and the same traffic needs more of them. The tempting fix is a bigger pm.max_children. Each child can use up to memory_limit, 128M by default. Set the cap too high and a traffic spike becomes an OOM kill of the whole container.
The pm.max_children calculation and pool config
This pool file suits a container that runs one FPM pool behind nginx. It replaces the stock www.conf:
[www]
user = www-data
group = www-data
listen = /run/php/php-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.backlog = 511
pm = static
pm.max_children = 20
pm.max_requests = 1000
pm.status_path = /fpm-status
pm.status_listen = 127.0.0.1:9001
ping.path = /fpm-ping
request_terminate_timeout = 30s
request_slowlog_timeout = 5s
slowlog = /var/log/php-fpm/www-slow.log
catch_workers_output = yes
Check the syntax with php-fpm -t. Debian and Ubuntu name the binary after the version, such as php-fpm8.3 -t.
Pick the pm mode.
statickeepspm.max_childrenchildren running at all times. In a container whose memory is reserved anyway, I usestatic. You skip the fork delay at the start of a spike, and the memory you size for is the memory you use.dynamickeeps betweenpm.min_spare_serversandpm.max_spare_serversidle children, up topm.max_children. It suits a VM where PHP shares memory with other services.ondemandforks children only when requests arrive and stops them afterpm.process_idle_timeout. It suits many small pools on one host. The first requests after a quiet spell pay for the fork.
Measure memory per child. Let the pool serve real traffic for a while, then read each child’s proportional set size:
for pid in $(pgrep -f 'php-fpm: pool www'); do
awk '/^Pss:/ {print $2}' "/proc/$pid/smaps_rollup"
done | sort -n | awk '{v[NR]=$1} END {printf "children=%d median=%.0fMB max=%.0fMB\n", NR, v[int((NR+1)/2)]/1024, v[NR]/1024}'
Run it as root or as the pool’s user. PSS splits shared pages between the processes that share them. RSS counts OPcache’s shared memory in full for every child, so a sum of RSS overstates your usage several times over.
Do the pm.max_children calculation. The rule is:
pm.max_children = (memory for PHP-FPM - opcache.memory_consumption - headroom) / max PSS per child
Memory for PHP-FPM is the container’s memory limit, minus anything else in the container, such as nginx. On a VM, it’s RAM minus the OS, the database and any other services. Keep a quarter of it as headroom for children that grow mid-request. Use the largest child you measured, not the median, because your heaviest endpoints set the peak. A 2 GiB container with 128 MB of OPcache and 60 MB children gives (2048 - 128 - 512) / 60, so about 23 children. Round down.
Check the result against CPU and the database. Children that wait on I/O use no CPU, so an I/O-heavy app can run many children per core. A CPU-heavy app gains nothing from children beyond a few per core, because they queue for CPU instead of the socket. Each child that opens a database connection holds one, so pods × pm.max_children must fit under the database’s connection limit. The MySQL too many connections recipe covers that side.
The other settings.
listen.backlogis how many connections can wait for a free child. 511 is the Linux default, and the kernel caps it atnet.core.somaxconn.pm.max_requestsrestarts a child after that many requests, which caps slow memory leaks. The default of 0 never restarts.pm.status_pathandpm.status_listenexpose the status page on a separate FastCGI listener. It still answers when every child in the main pool is busy, which is when you need it.request_terminate_timeoutkills a child that runs a request longer than this, and FPM logsexecution timed out (30.000000 sec), terminating. On Linux,max_execution_timedoesn’t count time spent in database queries or network calls, so it won’t stop a request stuck on a slow API. Keep this timeout below nginx’sfastcgi_read_timeout, 60 seconds by default, so FPM frees the child before nginx gives up.request_slowlog_timeoutwrites a PHP stack trace toslowlogfor any request slower than 5 seconds. It shows which call holds the children. Create/var/log/php-fpm/first, because FPM refuses to start when it can’t open that file.
Laravel and other frameworks gain more per child from OPcache and config caching than from extra children. The OPcache and Laravel recipe covers those.
Test it on your system
Test in staging with the same container limits and pm settings as production. This k6 script sends a fixed arrival rate, so FPM’s queue shows up as latency instead of slowing the test:
import http from 'k6/http';
import { check } from 'k6';
const paths = ['/', '/products?page=2', '/cart', '/api/stock/123'];
export const options = {
scenarios: {
peak: {
executor: 'constant-arrival-rate',
rate: Number(__ENV.RATE || 100), // your peak requests per second
timeUnit: '1s',
duration: '15m',
preAllocatedVUs: 200,
maxVUs: 2000,
},
},
thresholds: {
http_req_failed: ['rate<0.001'],
http_req_duration: ['p(99)<1000'],
},
};
export default function () {
const path = paths[Math.floor(Math.random() * paths.length)];
const res = http.get(`${__ENV.BASE_URL}${path}`);
check(res, { 'not 5xx': (r) => r.status < 500 });
}
Replace the paths with your real traffic mix, weighted toward your heaviest pages. Then run it at your peak rate.
Read the pool’s status while it runs. php-fpm_exporter can query the status listener without nginx:
php-fpm_exporter get --phpfpm.scrape-uri tcp://127.0.0.1:9001/fpm-status
Watch active processes against total processes, and listen queue. A listen queue above zero means requests are waiting for a child. Watch container memory with kubectl top pod, and nginx’s error log for the two upstream errors above. Rerun the PSS loop under load, since children grow on heavy pages.
Write your targets down first. A pass keeps listen queue at zero, or back to zero within seconds of a burst. Container memory stays under your chosen share of the limit, no execution timed out lines appear, and the k6 thresholds hold. If CPU pins at the limit while children sit busy, add pods instead of children.
Keep it healthy
Scrape the status listener with php-fpm_exporter, started with --phpfpm.scrape-uri tcp://127.0.0.1:9001/fpm-status. It serves metrics on port 9253. Its --phpfpm.fix-process-count flag recounts active and idle children, because FPM’s own counts can be off.
groups:
- name: php-fpm-pool
rules:
- alert: PhpFpmListenQueue
expr: max by (instance, pool) (phpfpm_listen_queue) > 0
for: 2m
labels:
severity: critical
annotations:
summary: "Requests are waiting for a PHP-FPM child in pool {{ $labels.pool }} on {{ $labels.instance }}"
description: "Every child is busy. Check the slowlog for the call holding children, then add pods, or raise pm.max_children if the memory math allows it."
- alert: PhpFpmMaxChildrenReached
expr: increase(phpfpm_max_children_reached[10m]) > 0
for: 1m
labels:
severity: warning
annotations:
summary: "PHP-FPM pool {{ $labels.pool }} hit pm.max_children"
description: "Works with pm dynamic or ondemand only. Rerun the PSS check and the pm.max_children calculation, or add pods before the next peak."
- alert: PhpFpmPoolBusy
expr: |
sum by (instance, pool) (phpfpm_active_processes)
/ sum by (instance, pool) (phpfpm_total_processes) > 0.9
for: 10m
labels:
severity: warning
annotations:
summary: "Over 90% of PHP-FPM children busy in pool {{ $labels.pool }} for 10 minutes"
description: "On pm static this is the early warning before the listen queue grows. Look for a slow dependency in the slowlog, or plan more pods."
- alert: PhpFpmDown
expr: phpfpm_up == 0
for: 2m
labels:
severity: critical
annotations:
summary: "php-fpm_exporter can't reach PHP-FPM on {{ $labels.instance }}"
description: "Check that the master runs and pm.status_listen answers. Run php-fpm -t to test the config after a change."
Set the 90% threshold from your own baseline. A pool sized tight to memory may run hot by design, and then the listen queue alert carries the weight.
Roll back
Copy the pool file before you edit it, and keep the copy next to the change in Git:
cp /usr/local/etc/php-fpm.d/www.conf /usr/local/etc/php-fpm.d/www.conf.before
The official Docker images keep pools in /usr/local/etc/php-fpm.d/. Debian and Ubuntu packages use /etc/php/8.3/fpm/pool.d/, and RHEL uses /etc/php-fpm.d/.
To revert, restore the file, run php-fpm -t, then reload the master with SIGUSR2 or systemctl reload php8.3-fpm. On Kubernetes, kubectl rollout undo deployment/web restores the previous image and ConfigMap reference.
If containers start getting OOM-killed after a raise, revert now. The next spike will kill them again. If the new values only failed to help, revert during a quiet hour and look at the slowlog before you try again.
More recipes
- Laravel OPcache, Config Cache and Route Cache
Size OPcache for your codebase and run Laravel's config cache and route cache on every deploy, so each request runs cached code instead of rebuilding it.
- Improve Cache Hit Ratio to Protect Your Origin at Peak
Trim the cache key, send cache headers from the origin and serve stale while revalidating, so the CDN absorbs peak traffic instead of passing it to your origin.
- Fix ALB 502 Bad Gateway and 504 Gateway Timeout
Set each target's keep-alive above the ALB idle timeout and keep slow requests under it, so the load balancer stops answering peak traffic with 502 and 504.
- Fix Lambda TooManyRequestsException Rate Exceeded
Size Lambda concurrency from peak traffic and split it with reserved and provisioned concurrency, so critical functions stop throttling when traffic spikes.