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.