How to Fix Nginx 504 Gateway Time-out Error
Quick Fix Summary
TL;DRIncrease proxy_read_timeout and fastcgi_read_timeout directives in your Nginx configuration.
Nginx returns a 504 Gateway Time-out when it fails to receive a timely response from an upstream server (like PHP-FPM, Node.js, or another proxy). This indicates the backend service is taking longer than Nginx's configured timeout to process the request.
Diagnosis & Causes
Recovery Steps
Step 1: Increase Nginx Proxy Timeout Directives
The primary fix is to increase the timeout Nginx waits for a response from the upstream server. Apply this in the `http`, `server`, or `location` block.
location / {
proxy_pass http://backend_server;
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 300s; # Increase this value (e.g., 300 seconds)
send_timeout 60s;
}Step 2: Increase FastCGI Timeout for PHP-FPM
If Nginx proxies to PHP-FPM via FastCGI, increase the `fastcgi_read_timeout` directive in your configuration.
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
fastcgi_read_timeout 300s; # Increase from default 60s
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}Step 3: Check and Tune Upstream Server (PHP-FPM)
Ensure your PHP-FPM pool configuration can handle the load and has appropriate timeouts. Key settings are `request_terminate_timeout` and `max_children`.
pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
request_terminate_timeout = 300 # Must be >= Nginx's fastcgi_read_timeout
request_slowlog_timeout = 10Step 4: Analyze Upstream Server Logs & Performance
Identify the slow component. Check application, database, and external service logs for errors or long-running operations.
# Tail PHP-FPM slow log (if configured)
tail -f /var/log/php8.1-fpm.log.slow
# Check for slow database queries (MySQL example)
SHOW PROCESSLIST;
# Monitor server resources in real-time
top -u www-dataStep 5: Implement Health Checks and Failover
For critical production, configure Nginx to mark slow upstreams as unhealthy and use backup servers.
upstream backend {
server backend1.example.com max_fails=3 fail_timeout=30s;
server backend2.example.com backup;
}Step 6: Test Configuration and Reload Nginx
Always test your configuration syntax before applying changes to avoid taking down the server.
sudo nginx -t
sudo systemctl reload nginx # Or: sudo service nginx reloadArchitect's Pro Tip
"Don't just set timeouts to 24 hours. Use increased timeouts (e.g., 300s) as a temporary shield while you use the slow logs to find and fix the actual root cause in your application code or database."
Frequently Asked Questions
What's the difference between proxy_read_timeout and fastcgi_read_timeout?
Use `proxy_read_timeout` when Nginx proxies to another HTTP server (Node.js, Apache, another Nginx). Use `fastcgi_read_timeout` when Nginx communicates with a FastCGI process like PHP-FPM.
I increased the timeouts but still get 504 errors. What next?
The bottleneck is now definitively upstream of Nginx. Investigate your application server's resource usage (CPU, RAM, I/O), database query performance, and calls to external APIs or microservices. Enable detailed logging in your app.
Can a 504 error be caused by the client?
No. A 504 Gateway Time-out is strictly a server-side error. It means Nginx (the gateway) did not get a response from the upstream server within its configured timeframe. Client-side slowness would result in a different error or timeout.