NGINX 502/504 Bad Gateway Triage Prompt
Turn a wall of error.log lines plus your upstream config into a ranked root-cause list and a concrete fix for 502/504 errors — without guessing or restarting blindly.
- Target user
- On-call engineers and platform teams debugging NGINX-to-backend failures under pressure
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior SRE who has triaged hundreds of NGINX gateway failures. You read error.log like a flight recorder: every line points at a layer (NGINX, network, or upstream). You never restart prod on a hunch.
I will provide:
- Relevant lines from the NGINX error log: [PASTE ERROR.LOG LINES]
- The relevant `upstream {}` block and the `location` that proxies to it: [PASTE NGINX CONFIG]
- What the backend is (app server, port, container, socket): [DESCRIBE BACKEND]
- When it started and whether it is constant or intermittent: [DESCRIBE PATTERN]
Do this, in order:
1. **Classify the error.** Distinguish 502 (`connect() failed`, `recv() failed`, `upstream prematurely closed connection`) from 504 (`upstream timed out`). Quote the exact log substring that tells you which.
2. **Localize the failure.** Decide whether the upstream is down, refusing connections, slow, returning a malformed response, or whether NGINX itself is misconfigured (wrong port/socket, wrong `proxy_pass` host, SELinux/AppArmor blocking the socket).
3. **Rank causes** most-to-least likely with the evidence behind each rank.
4. **Prescribe fixes.** For timeouts, show `proxy_connect_timeout` / `proxy_read_timeout` / `proxy_send_timeout` and whether raising them masks a real backend problem. For premature-close, address `keepalive` in the upstream and `proxy_http_version 1.1` + `proxy_set_header Connection ""`. For socket/permission issues, give the exact check.
5. **Verification commands** the user can run safely: `curl` direct to the backend, `ss -ltnp` on the upstream port, `nginx -t`, and a single-request reproduction.
Output: (a) a one-line verdict, (b) the ranked cause table with evidence, (c) a minimal config diff (only the lines that change), (d) the ordered verification commands. After any config change, run `nginx -t` and `nginx -s reload` — never hot-edit a running prod config in place.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Why this prompt works
A 502 and a 504 look identical to a user but have opposite root causes — one is the backend refusing or breaking the connection, the other is the backend being too slow. The prompt forces the model to quote the exact error.log substring that disambiguates them, so the diagnosis is grounded in evidence rather than a generic “check your backend.”
By demanding a ranked cause list with evidence and a minimal config diff, the output stays reviewable. You see exactly which lines change and why, instead of a rewritten config you have to re-audit.
The verification-commands step keeps a human in the loop. You confirm the backend is reachable with curl and ss before touching NGINX, and you gate every change behind nginx -t so a fat-fingered directive never reaches a live listener.
Related prompts
-
NGINX Config Security Audit Prompt
Audit an NGINX config for the classic misconfigurations — version leakage, missing security headers, open proxy, path traversal, exposed dotfiles — and get a prioritized fix list with exact directives, not a generic checklist.
-
Debug NGINX 502/504 Upstream Errors Prompt
Diagnose why NGINX returns 502 Bad Gateway or 504 Gateway Timeout from an upstream by correlating the error log, the proxy block, and upstream health into a ranked root-cause list with fixes.
-
NGINX Dynamic Upstream DNS Resolution Prompt
Make NGINX re-resolve backend DNS at runtime instead of caching it forever at startup — configure the resolver directive with variables in proxy_pass (or upstream re-resolution) — so proxying to cloud services, Kubernetes, or autoscaled targets stops sending traffic to dead IPs.
-
Fix NGINX Location Block Precedence Prompt
Untangle why the wrong NGINX location block is matching a request by tracing prefix vs regex vs exact-match precedence, then reorder/rewrite the blocks so each URL hits the intended handler.
More NGINX prompts & error guides
Browse every NGINX prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.