Nginx 502 and 504 Debugging Guide

Nginx 502 and 504 debugging guide for upstream health, proxy timeouts, logs, DNS, TLS and gateway ownership. Last updated August 31, 2026.

This guide is for the moment when Nginx is reachable but the upstream app, container or network path is failing behind it. Formalint keeps the page practical: start with observable evidence, keep commands repeatable, avoid pasting secrets into tools and write down the final decision so another developer can reproduce the fix.

The reference baseline for this page is Nginx proxy module. Vendor documentation defines the exact behavior, while this Formalint guide turns the behavior into a debugging workflow that is easier to follow during incidents, reviews and handoffs.

Fast triage order

Step	Question	Evidence to capture
1	Can you reproduce the issue with the smallest safe sample?	Input, command, URL, version, timestamp and environment name.
2	Is the failure syntax, configuration, transport, permission or runtime behavior?	Error message, status code, log line, stack trace or parser output.
3	Did the same check pass in another environment?	Working version, failing version, config difference and deploy reference.
4	What change would prove the root cause without hiding another issue?	One controlled fix, rollback path and follow-up test.

Useful checks

Confirm the exact tool, runtime, browser, server or database version before comparing behavior.
Reduce the example to a safe sample that keeps the shape of the problem but removes private data.
Prefer one repeatable command over screenshots when you need another person to verify the same behavior.
Record both the failing input and the corrected input so the fix becomes reviewable.

Commands and examples

nginx -t
tail -n 100 /var/log/nginx/error.log
curl -i http://127.0.0.1:3000/health

Decision checklist

Do not ship the fix until the failing case and at least one normal case both pass.
Check whether the issue belongs in code, configuration, infrastructure, documentation or user input handling.
If the page involves authentication, cookies, tokens, headers, database records or logs, redact values before sharing them.
Update the runbook, test fixture or team note while the details are still fresh.

Common mistakes

The most common mistake is treating the first visible error as the root cause. A timeout can be DNS, TLS, proxy, application, database or client retry behavior. A parser error can be invalid syntax, wrong encoding, invisible whitespace or a sample that no longer matches production. Keep the investigation narrow, but do not skip the boundary where the value crosses from one system into another.

Another mistake is fixing only the happy path. Good debugging leaves behind a small failure example, a working example and a note that explains why the chosen fix is safer than the alternatives considered.

Related Formalint pages

Continue with Nginx Reverse Proxy Checklist, Docker Compose Debugging, HTTP Status Codes, API Debugging Handbook.