Nginx 504 Gateway Timeout: The Definitive Diagnosis Order

Published October 2, 2026

⏱️ 2 min read

A 504 Gateway Timeout means nginx forwarded the request to an upstream (your app, another proxy, a database-backed service) and never got a response within its window. The fix depends entirely on which side is slow, so diagnose in this order.

Step 1: Time the upstream directly

Bypass nginx and hit the app the way nginx does:

time curl -s -o /dev/null http://127.0.0.1:3000/endpoint

If the app itself takes 30+ seconds, nginx is innocent — the fix is in the application (slow query, lock contention, cold start, retry storm). Profile there; do not raise proxy timeouts to hide it.

Step 2: Check what nginx allows

Defaults are 60s (proxy_read_timeout). If your workload legitimately needs longer:

location /slow/ { proxy_read_timeout 180s; }

Only raise it for the routes that need it, not globally — a global raise turns real outages into 3-minute hangs.

Step 3: Check the upstream pool

With more than one upstream server, one dead peer can poison the rotation. A max_fails/fail_timeout setup should eject it, but proxy_next_upstream defaults do not include timeouts unless you say so:

proxy_next_upstream error timeout http_502 http_504;

Verify who is slow per-peer with a quick loop over the pool members.

Step 4: Beware the queue in front of you

If nginx itself sits behind a CDN (Cloudflare, for example), the edge has its own timeout budget — a 524 from Cloudflare is the same class of problem with the edge in the middle. The error page's headers and server signature tell you which layer is speaking. Each layer must have a timeout budget larger than the one inside it, or the outer layer gives up first.

Step 5: The keepalive trap

upstream blocks without keepalive open a new TCP connection per request. Under load, ephemeral port exhaustion can look exactly like 504s under peak traffic only. Add:

upstream app { server 127.0.0.1:3000; keepalive 32; }

and proxy_http_version 1.1; proxy_set_header Connection "";.

The 60-second summary

Time the app directly → check proxy timeouts → inspect upstream health → count the layers in front → fix connection reuse. 504s are never "nginx being slow" — nginx is just the messenger with a stopwatch.

Latency-sensitive stacks deserve an edge in front of them — see our cloud pick for latency budgets (partner link).