Incident Guide · Nginx
502 Bad Gateway: it's almost never Nginx
Most engineers assume a 502 means Nginx is broken. It doesn't. A 502 usually means Nginx is working correctly — the upstream application isn't. Here's how to find the real cause in minutes.
The three status codes people confuse
502
Upstream returned an invalid or no response
503
Service unavailable or refusing requests
504
Upstream took too long to respond
Three status codes, three different root causes, three different troubleshooting paths. Treating them the same wastes the first 20 minutes of most incidents.
Check this first
Before touching any Nginx config, look at the actual error log:
tail -50 /var/log/nginx/error.log
The specific error text tells you which of the causes below you're dealing with — don't guess before you look.
Common causes, ranked by likelihood
1Backend isn't running
Error log shows connect() failed (111: Connection refused). The upstream service crashed, hasn't started yet, or is bound to the wrong port. Check systemctl status or your container's process list before anything else.
2Upstream timeout too low for real workload
The backend is running but slow — a heavy query, cold cache, or resource contention pushes response time past Nginx's proxy_read_timeout. Check backend response times directly before raising the timeout, which only delays the same failure.
3Wrong upstream host or port in config
A recent deploy changed the backend's port or hostname (common after a container restart with dynamic port assignment) but the Nginx config wasn't updated. Diff the current proxy_pass directive against what's actually running.
4Backend crashed under load
Works fine at low traffic, fails at peak. Check backend memory/CPU at the time of the 502 — this is a capacity problem, not a routing problem, and won't be fixed by touching Nginx at all.
What not to do
Don't restart Nginx as a first step. If Nginx is healthy and the upstream is the actual problem, restarting Nginx does nothing except lose your current error log — the exact evidence you need to diagnose this properly.
Paste this exact error and get a ranked diagnosis
OperatorMesh reads your actual error log text and Nginx config context, then ranks the likely cause with a confidence score — instead of working through this list manually.
⚡ Try it free →