Management Guides Troubleshooting

WordPress 504 Gateway Time-out on Nginx: Causes and Fixes

A 504 Gateway Time-out means PHP answered too late. Learn which timeout fires first, how to find the slow request, and when raising a limit is the right fix.

"504 Gateway Time-out" from nginx means nginx passed the request to PHP-FPM and waited, and no answer arrived within the time limit. PHP did not crash and did not answer wrongly, which would be a 502 Bad Gateway. It was still working, or still waiting in a queue, when nginx gave up.

Raising the timeout hides the symptom for ordinary pages. The lasting fix is to find the slow request: a long import or backup, a slow database query, a call to an outside service that does not answer, or every PHP worker being busy. Raise a limit only for jobs that are long by nature, and only for the URL that needs it.

The directives and commands below are taken from the nginx, PHP and WP-CLI documentation and were not run on a test server for this article.

What you see and where to look

What you seeLikely causeWhere to look
504 after about 60 seconds on one admin action (import, update, backup)A long job run through the browsernginx error log, then WP-CLI
504 on ordinary pages at busy timesAll PHP workers busy; requests wait in the queuePHP-FPM log, pm.max_children
504 on specific pages at any timeSlow query or slow outside API callPHP-FPM slow log, database slow query log
Cloudflare error 524 instead of 504The origin took longer than Cloudflare's own limitSame checks; Cloudflare timeout
"Critical error" after about 30 seconds instead of 504PHP max_execution_time reachedPHP error log

Confirm that it is a timeout. The nginx error log has a line for every 504:

sudo grep "upstream timed out" /var/log/nginx/error.log | tail -n 5

The line ends with the request and the upstream, for example upstream timed out (110: Connection timed out) while reading response header from upstream, ... request: "POST /wp-admin/admin-ajax.php HTTP/2.0". Note the URL.

The chain of timeouts

Four limits apply to one request. Which one fires first decides the error you see.

LimitDefaultWhat it measuresResult when reached
PHP max_execution_time30 secondsTime the script itself runs. On Linux, time spent waiting for the database or a network call is not counted.PHP fatal error; WordPress shows its critical error page
nginx fastcgi_read_timeout60 secondsTime between two reads from PHP-FPM, in practice the wait for the response to start504 Gateway Time-out
PHP-FPM request_terminate_timeout0 (off)Real elapsed time of the requestThe worker is killed; nginx returns 502
Cloudflare proxy read timeoutSet by CloudflareTime Cloudflare waits for the origin's responseCloudflare error 524

The first row explains why a 504 is so common. A request that spends its time waiting for a slow query or a remote server uses almost none of its 30 seconds of max_execution_time, so PHP never stops it, and the 60-second nginx limit is reached first. Nginx giving up does not stop PHP: the worker keeps running the request and stays unavailable to other visitors until it finishes.

For sites proxied through Cloudflare, Cloudflare's documentation for error 524 gave a default of 125 seconds when this article was written, adjustable only on Enterprise plans; check that page for the current figure. Raising nginx and PHP limits above it has no effect for proxied visitors. A 504 shown on a Cloudflare-branded page is your origin's own 504 passed through.

If nginx is a reverse proxy in front of another web server, for example WordPress in Docker, the nginx directive is proxy_read_timeout, with the same 60-second default.

Find the slow part with the PHP-FPM slow log

PHP-FPM can write a stack trace, the list of functions a script is inside, for every request that runs longer than a threshold. Enable it in the pool file: /etc/php/8.5/fpm/pool.d/www.conf on Ubuntu and Debian (use your PHP version), /etc/php-fpm.d/www.conf on AlmaLinux and Rocky Linux.

request_slowlog_timeout = 5s
; AlmaLinux, Rocky Linux: keep the slowlog line the package already has and read that file instead
slowlog = /var/log/php-fpm-slow.log
# Ubuntu, Debian
sudo php-fpm8.5 -t && sudo systemctl reload php8.5-fpm
# AlmaLinux, Rocky Linux
sudo php-fpm -t && sudo systemctl reload php-fpm

# repeat the slow request, then
sudo tail -n 40 /var/log/php-fpm-slow.log

Each entry names the script and the functions it was in. Read the top lines of the trace:

  • mysqli_query(): the request is waiting for the database. Turn on the slow query log to see which statement: sudo mariadb -e "SET GLOBAL slow_query_log = 1; SET GLOBAL long_query_time = 2; SHOW VARIABLES LIKE 'slow_query_log_file';", then read the file it prints. The setting lasts until the database restarts.
  • curl_exec(): WordPress is waiting for another server, such as a licence check, a payment or shipping API, or a remote feed. The lines below it in the trace name the plugin.
  • Plugin or theme functions: the code itself is slow, often a report or an export over a large table.

Why is WordPress slow goes further into reading these logs.

All workers busy

PHP-FPM runs a fixed maximum number of worker processes, set by pm.max_children. When all of them are occupied, new requests wait, and the nginx timer runs while they wait. Fast pages then return 504 too. The PHP-FPM log records it:

sudo grep "max_children" /var/log/php8.5-fpm.log          # Ubuntu, Debian
sudo grep "max_children" /var/log/php-fpm/error.log       # AlmaLinux, Rocky Linux

A line such as server reached pm.max_children setting (5), consider raising it confirms it. Raise the number only if the server has memory for more workers; PHP-FPM tuning shows how to calculate it. If a few slow requests are holding the workers, fixing those requests frees the pool, and a page cache reduces how many requests need a worker at all.

If the 504s come at regular intervals, overlapping scheduled tasks are the likely cause; see WordPress cron jobs.

When raising the timeout is legitimate

Some admin jobs are long by nature: importing a large export file, a migration plugin restoring a site, a bulk image regeneration. For those, raise the limit for the one script, not for the whole site. Add an exact-match location above the general PHP block in the site's server block, with the same FastCGI lines your PHP block uses:

location = /wp-admin/admin.php {
    include snippets/fastcgi-php.conf;            # Ubuntu, Debian; copy the lines from your own PHP location
    fastcgi_pass unix:/run/php/php8.5-fpm.sock;   # AlmaLinux, Rocky Linux: unix:/run/php-fpm/www.sock
    fastcgi_read_timeout 300s;
}
sudo nginx -t && sudo systemctl reload nginx

Use the path from the error log line; imports started from Tools run through /wp-admin/admin.php, many plugin jobs through /wp-admin/admin-ajax.php. Verify by repeating the job and checking that no new "upstream timed out" line appears.

If the job now ends with a critical error instead, PHP's own limit was reached and the PHP error log says "Maximum execution time of 30 seconds exceeded". Raise max_execution_time in the FPM php.ini (/etc/php/8.5/fpm/php.ini, or /etc/php.ini on AlmaLinux and Rocky Linux), reload PHP-FPM, and check the new value under Tools → Site Health → Info → Server. If the pool sets request_terminate_timeout, it must be at least as long. Behind Cloudflare, none of this helps beyond Cloudflare's limit.

Run long jobs with WP-CLI

The command line has no gateway in front of it, and PHP's command-line default for max_execution_time is 0, meaning no limit. Run it as the web server user so that file ownership stays correct:

cd /var/www/example.com
# the web user is www-data on Ubuntu, Debian; nginx or apache on AlmaLinux, Rocky Linux
sudo -u www-data wp core update
sudo -u www-data wp plugin update --all
sudo -u www-data wp import export.xml --authors=create     # needs the WordPress Importer plugin
sudo -u www-data wp search-replace 'http://old.example' 'https://example.com' --dry-run
sudo -u www-data wp cron event run --due-now

Each command prints its result, which is the verification. For jobs that run for many minutes, start them inside tmux or screen so that a dropped SSH session does not interrupt them. The WP-CLI guide covers installation and the commands used most often.

Settings that keep 504s away

  • Leave the global fastcgi_read_timeout at its default. A page that needs more than 60 seconds is a fault to investigate.
  • Keep the slow log enabled with a threshold of a few seconds.
  • Set request_terminate_timeout a little above the longest nginx timeout you configured, so that a stuck request cannot hold a worker for hours.
  • Run imports, updates, search-and-replace and backups from the shell.
Share story:

Continue reading other guides on How VPS.