Nginx: 504 Gateway Timeout

Nginx returns a 504 Gateway Timeout error when the upstream backend server does not send a response within the configured timeout period.

The 504 Gateway Timeout error may appear as:

• 504 Gateway Timeout
• 504 Gateway Time-Out
• 504 Gateway Timeout NGINX
• HTTP 504 Gateway Timeout
• Gateway Timeout (504)

When Nginx Produces the 504 Gateway Timeout Error

Nginx produces the 504 Gateway Timeout error when it forwards a request to an upstream server and the upstream does not respond before the timeout expires. This happens when Nginx acts as a reverse proxy using proxy_pass or when Nginx communicates with PHP-FPM using fastcgi_pass.

Nginx also returns a 504 when the upstream server is under heavy load, running slow database queries, or processing long-running scripts. The Nginx error log shows upstream timed out (110: Connection timed out) while reading response header from upstream when this occurs.

What Causes the 504 Gateway Timeout Error in Nginx

Nginx returns 504 when proxy_read_timeout is too low for the upstream response time.The proxy_read_timeout directive sets how long Nginx waits for a response from a proxied upstream server. The default is 60 seconds. If the upstream application takes longer than this value to process a request, Nginx closes the connection and returns 504.

Nginx returns 504 when fastcgi_read_timeout is too low for PHP-FPM execution.The fastcgi_read_timeout directive controls how long Nginx waits for PHP-FPM to finish processing a PHP script. Slow PHP scripts that run database migrations, process large file uploads, or generate complex reports can exceed this timeout.

Nginx returns 504 when the upstream server is down or unreachable.Network issues, firewall rules, or a crashed application server prevent Nginx from receiving any response. Nginx waits for the proxy_connect_timeout period and then returns 504 if no connection is established.

Nginx returns 504 when PHP's max_execution_time is lower than the Nginx timeout.PHP terminates a script when it exceeds max_execution_time in php.ini. If this value is lower than the fastcgi_read_timeout in nginx.conf, PHP kills the script before Nginx times out. The result is either a 504 or a blank response.

How to Fix the 504 Gateway Timeout Error in Nginx

Fix for PHP-FPM Backends

1. Increase the max_execution_time value in the PHP configuration file. Open php.ini and set a higher value:

sudo vi /etc/php/8.2/fpm/php.ini

max_execution_time = 300

2. Add or increase the fastcgi_read_timeout directive in the Nginx location block that handles PHP requests. Nginx uses this value to determine how long to wait for PHP-FPM to return a response.

server {
    location ~ \.php$ {
        root /var/www/example.com;
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 300;
    }
}

3. Restart PHP-FPM and reload Nginx to apply both changes:

sudo systemctl restart php8.2-fpm
sudo nginx -t
sudo systemctl reload nginx

Fix for Reverse Proxy Backends

1. Increase the proxy timeout directives in the Nginx location block that forwards requests to the upstream application. The proxy_read_timeout directive controls how long Nginx waits for the upstream to send a response.

server {
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_connect_timeout 60;
        proxy_send_timeout 300;
        proxy_read_timeout 300;
        send_timeout 300;
    }
}

2. Test the configuration and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

How to Verify the Fix

Nginx stops returning 504 errors when the upstream server responds within the new timeout limit. Send a request to a slow endpoint and confirm it completes successfully:

curl -o /dev/null -s -w "%{http_code}\n" http://example.com/slow-endpoint

A 200 status code confirms the timeout is now long enough. Check the Nginx error log to verify that no new upstream timed out entries appear:

tail -20 /var/log/nginx/error.log

Edge Cases and Variations

Nginx returns 504 even after increasing timeouts.The upstream application may have its own timeout settings that terminate the process before the Nginx timeout. For PHP-FPM, check request_terminate_timeout in the pool configuration at /etc/php/8.2/fpm/pool.d/www.conf. This setting kills PHP workers that exceed the time limit, regardless of the Nginx fastcgi_read_timeout value.

Nginx returns 504 for specific endpoints only.Increase the timeout in a dedicated location block for the slow endpoint rather than applying a global timeout increase. A global increase masks performance problems and allows all requests to consume more server resources.

location /api/reports {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 600;
}

Nginx returns 504 behind a load balancer or CDN.The load balancer or CDN has its own timeout settings. Ensure that each layer in the request chain has a timeout greater than or equal to the layer behind it. A CDN with a 30-second timeout triggers a 504 even if Nginx allows 300 seconds.

Related Nginx Errors

Nginx: 502 Bad Gateway-- Nginx returns 502 when the upstream connection fails entirely. A 504 indicates the connection was established but the response took too long.

Nginx: upstream sent too big header while reading response header-- Large response headers can cause delays that contribute to timeout issues when combined with small buffer sizes.