504 Gateway Timeout with Nginx

Nginx returns:

504 Gateway Timeout

This is the close cousin of a 502, and the difference matters. A 502 means Nginx couldn't reach your app at all. A 504 means Nginx did reach it, sent the request, and then waited — and your app didn't respond within the allowed time. The app is up. It's just too slow for this request.

Cause 1: The request genuinely takes too long

By far the most common. A slow database query, an external API call that hangs, a heavy report — the work outlasts Nginx's patience (default proxy_read_timeout is 60s). Find the slow endpoint in your app's logs and time it:

tail -f /var/log/nginx/error.log     # look for: upstream timed out (110: Connection timed out)

That upstream timed out line is the signature of a 504.

Cause 2: The app is overloaded, not one request

If lots of requests suddenly 504 together, the app isn't slow per request — it's out of workers or threads and requests are queuing. Check whether your app server (gunicorn, uvicorn, PHP-FPM) has enough workers for the traffic.

Fix path A: Make the request faster (do this first)

Raising the timeout hides the symptom; it doesn't make users wait less. Always try to fix the slow query or offload the heavy work to a background job before you touch Nginx timeouts.

Fix path B: Raise the timeout for genuinely long work

Some work is legitimately slow (a big export, a long upload). Give Nginx more patience for it:

location /export {
    proxy_pass http://127.0.0.1:8000;
    proxy_read_timeout 300s;     # wait up to 5 minutes for this route
}

Reload after editing:

nginx -t && systemctl reload nginx    # test config, then apply

Scope the longer timeout to the slow location — don't loosen it globally, or you'll let every hung request tie up a connection.

The checklist

1. 504 = app reached but too slow (vs 502 = not reached).
2. grep "upstream timed out" in the Nginx error log to confirm.
3. Fix the slow query or move heavy work to a background job first.
4. Only then raise proxy_read_timeout — scoped to the slow route.

Frequently Asked Questions

How do I increase the timeout in Nginx? Raise proxy_read_timeout (and, for slow uploads, proxy_send_timeout / proxy_connect_timeout) on the specific location that needs it, then nginx -t && systemctl reload nginx. Scope it to the slow route rather than loosening it globally.

What's the difference between a 502 and a 504 in Nginx? A 502 Bad Gateway means Nginx couldn't reach your app at all; a 504 Gateway Timeout means it reached the app but the app didn't answer in time. 502 is "not there", 504 is "too slow".

Why does my Nginx 504 only happen on some requests? Those endpoints are genuinely slow — a heavy query, a big export, a hung external API call. Fix or background the slow work before raising the timeout; a higher timeout just makes users wait longer for the same slow response.