HTTP 502 Bad Gateway: Server Communication Error

TL;DR: A 502 usually means your edge server is alive, but the service behind it answered in a way the edge could not use.

What A 502 Is Really Telling You

502 Bad Gateway is a proxy-layer error. The browser reached nginx, Cloudflare, a load balancer, or another gateway successfully. That layer then tried to talk to an upstream app and got back something broken, incomplete, or impossible to parse.

Client -> Proxy or CDN -> App server
                     \-> invalid upstream response -> 502

That is why a 502 often feels confusing: the system that returns the error is not always the system that caused it.

The Most Common Real Causes

1. The upstream is not actually listening

The proxy points at 127.0.0.1:3000, but the app crashed, moved ports, or never started.

2. The upstream closed the connection too early

The app accepted the request, then died, crashed, or reset the socket before finishing the HTTP response.

3. The upstream returned something malformed

Examples:

• invalid headers
• partial response bytes
• HTTP spoken on a port expecting FastCGI or gRPC
• TLS expected on one side but plain HTTP sent on the other

4. Connection reuse is misconfigured

Under load, keep-alive mismatches can create intermittent 502s that disappear on refresh and only show up in bursts.

Start The Investigation Here

Check the proxy error log before the app log. The proxy usually tells you what kind of bad upstream behavior it saw.

Typical clues:

• connection refused
• upstream prematurely closed connection
• upstream sent invalid header
• recv() failed

Those are much more actionable than the browser’s generic “502 Bad Gateway.”

A Good Debugging Order

1. Confirm which proxy layer emitted the 502.
2. Check that layer’s error log.
3. Hit the upstream directly with curl.
4. Confirm the upstream process, port, and protocol.
5. Compare proxy and upstream timeout and keep-alive settings.

Direct Checks

# Is the app running where the proxy expects it?
curl -v http://127.0.0.1:3000/health

# Is the service process healthy?
systemctl status your-app

# What is nginx complaining about?
tail -f /var/log/nginx/error.log

If the app answers directly but the proxy still returns 502, the issue is often protocol mismatch, header formatting, or connection reuse rather than pure app downtime.

502 vs 503 vs 504

Code	What it usually means
502	Upstream answered incorrectly
503	Service is unavailable or intentionally shedding work
504	Upstream did not answer before timeout

That distinction matters for retries. A flaky 502 often points to integration or transport problems. A 503 often points to capacity or maintenance. A 504 points to slowness.

The Practical Fix Mindset

Do not treat 502 as “the server is down.” Treat it as “a boundary between two services is unhealthy.” That framing gets you to the right logs faster.

Related

• 500 Internal Server Error
• 503 Service Unavailable
• 504 Gateway Timeout