HTTP 502 bad gateway

What a 502 means

A 502 Bad Gateway is the honest middleman gossip: a proxy or gateway (nginx, Apache with proxy_pass, Cloudflare, a load balancer) tried to forward your request to an upstream server, and the upstream answered with something unusable: a protocol error, a timeout, a TCP refusal, or a response that ended mid-stream. The client cannot tell whether the upstream simply crashed at that moment or the route is misconfigured; the fix order asks exactly that question.

Common causes

• PHP-FPM or the app worker is dead or hung. nginx receives nothing back and closes the request with 502.
• The application takes longer than the proxy timeout (30s, 60s, whatever the platform sets), so the proxy kills the request.
• The origin refused the connection: the port in the config is closed, the app binds 127.0.0.1 while the proxy listens on that port, or the service is stopped.
• A deploy went mid-way and the upstream binary is still starting, or the process keeps crashing on boot.
• Resource exhaustion: CPU spike, memory cgroup kill, or too many open files kills the app mid-request.
• A single slow or broken endpoint poisons one worker, and the pool drains until every new request route 502s.

The ordered fix

1. Repeat the 502 after a pause. Make a couple of page loads in a private window separated by a second. If it transiently 200s, the pool is flapping; if it never succeeds, the route or process is down.
2. Check the process. Confirm the app process and the socket it listens on are alive and up:

- systemctl status php-fpm and systemctl status nginx on a systemd host.

- curl the app directly, bypassing the proxy: curl localhost:8080/health.

- ss -tlnp | grep :8080 to confirm the port is bound.

1. Read both logs in order. The nginx error log records upstream timed out or no live upstreams; the PHP-FPM or app log then tells you the underlying failure (out of memory, missing file, a fatal exception).
2. Restart in the right order the upstream first, wait for it to become healthy, then the proxy. If the proxy comes up first it floods the not-yet-listening port with 502s.
3. Beware timeouts. If the workload is a legitimately long job, raise the proxy timeout (nginx proxy_read_timeout), move the work to background, or stream the response early.
4. Check the deploy. A 502 that starts exactly after a release means the binary failed to boot. Roll back the app (not the proxy) and watch the app log on the old version.
5. On Cloudflare, a 522 is the edge-to-origin variant, while a 502 means the origin answered in an unusable way. Check the origin logs and confirm the origin actually answers the IP Cloudflare sends.

Verify

# Is the origin up at all, bypassing the gateway?
curl -i http://127.0.0.1:8080/api/health
# 200 OK means the app is fine and the proxy/bind is the problem

# From the proxy, is the same request a 502 again?
curl -sI https://example.com/api/health
HTTP/2 502

Prevention

• Put a health endpoint on the app and a load-balancer that pulls the worker out and restarts it.
• Keep the proxy and app logs in one time zone and one tail, so a 502 has a matching error line.
• Watch deploy coverage: a config map or environment file is the first thing people change when a 502 begins.
• Run the app under a process supervisor that restarts it on exit, so crashes are seconds, not an outage.

When to involve a professional

If the upstream is healthy on 127.0.0.1 and the gateway still 502s, the issue is a binary mismatch between the bind and the proxy: IPv6, port, or a wrong hostname. A host or a senior sysadmin can diff the two configs in minutes; do not reinstall the app over it.