nginx: 502 Bad Gateway from an upstream

Hi, it's BlueByte. A 502 Bad Gateway from nginx means nginx itself is fine — it's the upstream behind it that didn't answer, or answered with something nginx couldn't use. The symptom is nginx returning 502 even though its own nginx -t passes. We'll walk through what a 502 really means, how to read the error log to find the exact failure, fix it per cause, and keep it from recurring.

What a 502 from nginx actually means

The browser shows a short page and the access log records the status:

203.0.113.7 - - [04/Sep/2026:11:20:03 +0900] "GET /api HTTP/1.1" 502 552 "-" "curl/8.4.0"

nginx accepted the request, tried to proxy it to the server named in proxy_pass, and either couldn't connect or got a reply it considers invalid. This is not nginx being down — nginx is up and answering; the gateway behind it is the problem. That's why restarting nginx rarely helps.

The four things that make an upstream unusable

A 502 comes from one of these:

• The upstream isn't running or isn't listening on the address in proxy_pass — the connection is refused.
• proxy_pass points at the wrong host, port, or socket — nginx connects to nothing.
• The upstream crashed or closed the connection mid-response, so nginx read an empty or truncated reply.
• The upstream's response header is larger than proxy_buffer_size (default 4k/8k), so nginx rejects it as invalid.

A slow-but-alive upstream is a separate error — that's a 504, covered at the end.

Read the error log — it names the exact failure

The access log shows 502; the error log says why. Watch it while you reproduce the request:

sudo tail -f /var/log/nginx/error.log

2026/09/04 11:20:03 [error] 812#812: *5 connect() failed (111: Connection refused)
  while connecting to upstream, client: 203.0.113.7, upstream: "http://127.0.0.1:8000/api"

Read the parenthetical. (111: Connection refused) means nothing is listening; upstream prematurely closed connection means the app died mid-reply; upstream sent too big header means the header overflowed the buffer; (13: Permission denied) usually means SELinux is blocking the outbound connection on RHEL. The upstream: field prints the exact address nginx tried — check it matches where your app actually listens.

Fix it by cause: dead upstream, wrong address, big headers

1. Upstream not listening — confirm what's on the port, then start the app:

ss -ltnp | grep :8000
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/api

If curl also fails, nginx is innocent — fix the app. A working upstream prints 200.

2. Wrong proxy_pass — point it at the real address and reload:

location /api {
    proxy_pass http://127.0.0.1:8000;
}

3. Header too big — raise the buffers for that location:

proxy_buffer_size 16k;
proxy_buffers 8 16k;

A real case: the app crashed and left the socket dead

Your Node app behind nginx starts throwing 502s. nginx -t is fine, so you run tail -f /var/log/nginx/error.log and see connect() failed (111: Connection refused) while connecting to upstream: "http://127.0.0.1:3000/". You run ss -ltnp | grep :3000 and nothing is listening — the app process exited overnight and its port is free. You restart the service with systemctl restart myapp, curl http://127.0.0.1:3000/ returns 200, and the 502s stop immediately. nginx was reporting the truth all along: there was no gateway to reach.

Confirm the proxy path end to end

Test the config, reload, then request through nginx:

sudo nginx -t && sudo nginx -s reload
curl -I https://example.com/api

HTTP/1.1 200 OK

A 200 (or your app's normal status) through the public URL means nginx reached the upstream and passed the response back. Keep the error log open during the test — a clean request leaves no new [error] line.

Keep 502s from coming back

Run the upstream under a supervisor — systemd, a container restart policy, or a process manager — so a crash restarts it instead of leaving a dead port. Add a health check so an unready backend is pulled from rotation before it can serve a 502. On RHEL/SELinux hosts, allow nginx to make outbound connections once with sudo setsebool -P httpd_can_network_connect 1. Size proxy_buffer_size for the largest header your app sends — oversized auth tokens and cookies are a common overflow cause. If the 502s are intermittent and the log shows upstream prematurely closed connection, the backend is likely closing idle keepalive connections before nginx reuses them — set proxy_http_version 1.1 with an upstream keepalive count, or shorten the backend's idle timeout so nginx never picks a stale connection.

How a 502 differs from a 504

A 502 Bad Gateway means the upstream was unreachable or sent an invalid response — the connection failed or the reply was broken. A 504 Gateway Timeout means the upstream was reachable but too slow: it didn't answer within proxy_connect_timeout, proxy_send_timeout, or proxy_read_timeout (each default 60s). If the error log says upstream timed out, raise the relevant timeout or make the backend faster — that's a 504, not a 502.