All technical articles

Tune PHP-FPM and Fix 504 Gateway Timeout: A Practical Pool Guide

Fix Nginx and PHP-FPM 504 errors by measuring pool saturation, sizing pm.max_children, enabling slowlog, and aligning timeout settings safely.

Tune PHP-FPM and Fix 504 Gateway Timeout: A Practical Pool Guide

A 504 means the proxy waited for PHP-FPM but did not receive a response before its deadline. Raising a timeout may hide the symptom for a while, yet a saturated pool, blocked worker, slow query, or external API call will bring it back. The durable fix starts by locating where the request spends its time.

Identify which layer owns the timeout

In a common stack, Nginx passes PHP requests to a FastCGI socket. A 502 usually points to a broken connection or unavailable upstream; a 504 means the upstream did not answer in time. Correlate the request timestamp across Nginx access/error logs and the PHP-FPM journal.

sudo tail -f /var/log/nginx/error.log
sudo journalctl -u php8.3-fpm -f
sudo grep -R "upstream timed out" /var/log/nginx/

Prove pool saturation before tuning

The message server reached pm.max_children is direct evidence that all workers were busy. Do not respond by adding workers blindly: each process consumes memory, and an oversized pool can trigger swapping or the OOM Killer. Measure real worker RSS during representative traffic.

ps --no-headers -o rss,cmd -C php-fpm8.3 | awk '{sum+=$1;n++} END {print sum/n/1024 " MB per worker"}'
ss -xl | grep php
systemctl status php8.3-fpm

Size pm.max_children from a memory budget

Start with the memory reserved for the pool divided by average worker memory, then keep headroom for spikes. If PHP has 2 GB and workers average 80 MB, 25 is a theoretical ceiling, not a target. Leave capacity for Nginx, the database, cache, kernel, and monitoring.

[www]
pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 4
pm.max_spare_servers = 8
pm.max_requests = 500
request_terminate_timeout = 120s

Enable slowlog to expose slow execution

Slowlog records a PHP stack trace when a request exceeds a threshold. It often identifies a plugin hook, database call, filesystem operation, or remote HTTP dependency that should be fixed instead of merely given more time.

request_slowlog_timeout = 5s
slowlog = /var/log/php-fpm/www-slow.log

sudo php-fpm8.3 -tt
sudo systemctl reload php8.3-fpm

Align timeouts across the stack

Set fastcgi_read_timeout slightly above the legitimate maximum request duration. Review PHP max_execution_time, FPM request_terminate_timeout, and load-balancer limits together. Move exports, imports, image processing, and bulk jobs to a queue rather than keeping a web request open for minutes.

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_connect_timeout 5s;
    fastcgi_send_timeout 60s;
    fastcgi_read_timeout 120s;
}

Validate with controlled load and metrics

Compare the 504 rate, p95 latency, active/idle workers, socket queue, CPU, and memory before and after each change. If more workers push CPU to 100%, the bottleneck is compute or application code. Apply one change at a time and keep a rollback copy.

504 troubleshooting checklist

  • Correlate timestamps in Nginx and PHP-FPM logs.
  • Check for pm.max_children warnings and OOM events.
  • Measure worker RSS under realistic traffic.
  • Enable slowlog and fix the slow endpoint.
  • Align timeouts across proxy, FPM, PHP, and load balancer.
  • Validate configurations with php-fpm -tt and nginx -t.

Frequently asked questions

Is increasing fastcgi_read_timeout enough?

No. It only makes Nginx wait longer. Pool saturation, slow SQL, locks, and external dependencies still need to be corrected.

Should I use dynamic or ondemand?

Dynamic usually gives steadier latency under continuous traffic. Ondemand saves memory on quiet sites but pays worker startup cost.

Why did the server slow down after increasing max_children?

Too many workers can exhaust RAM, create swap pressure, and compete for CPU. Size the pool from measured resource budgets.

Related guides