Skip to content
🎉 Launch sale:50% off everything over $22 — automatically applied at checkout· ends Aug 2Shop the sale →
DevOps AI ToolKit
Newsletter
All prompts
AI for NGINX Difficulty: Intermediate ClaudeChatGPTCursor

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

More NGINX prompts & error guides

Browse every NGINX prompt and troubleshooting guide in one place.

Free download · 368-page PDF

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.