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 see | Likely cause | Where to look |
|---|---|---|
| 504 after about 60 seconds on one admin action (import, update, backup) | A long job run through the browser | nginx error log, then WP-CLI |
| 504 on ordinary pages at busy times | All PHP workers busy; requests wait in the queue | PHP-FPM log, pm.max_children |
| 504 on specific pages at any time | Slow query or slow outside API call | PHP-FPM slow log, database slow query log |
| Cloudflare error 524 instead of 504 | The origin took longer than Cloudflare's own limit | Same checks; Cloudflare timeout |
| "Critical error" after about 30 seconds instead of 504 | PHP max_execution_time reached | PHP 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.
| Limit | Default | What it measures | Result when reached |
|---|---|---|---|
PHP max_execution_time | 30 seconds | Time 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_timeout | 60 seconds | Time between two reads from PHP-FPM, in practice the wait for the response to start | 504 Gateway Time-out |
PHP-FPM request_terminate_timeout | 0 (off) | Real elapsed time of the request | The worker is killed; nginx returns 502 |
| Cloudflare proxy read timeout | Set by Cloudflare | Time Cloudflare waits for the origin's response | Cloudflare 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_timeoutat 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_timeouta 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.