502 Bad Gateway: what it means and how to fix it

02Which server returned the 502?

Answer this before changing anything. A branded page from your CDN or WAF means the edge got no valid answer from your origin; a bare "502 Bad Gateway" with an nginx footer usually comes from the proxy on your own server. Response headers such as Server and Via, which curl -sI shows, name the last hop that answered.

03Which error log lines explain a 502?

With nginx in front of the application on Debian or Ubuntu, the reason is almost always in /var/log/nginx/error.log, written in the same second as the 502 in the access log. The table explains the lines that matter; the raw lines below were reproduced on nginx 1.22.1 against deliberately broken test backends, with addresses and paths shortened.

connect() failed (111: Connection refused) while connecting to upstream, upstream: "http://127.0.0.1:8000/"
connect() to unix:/run/php/php8.2-fpm.sock failed (2: No such file or directory) while connecting to upstream
connect() to unix:/run/php/php8.2-fpm.sock failed (13: Permission denied) while connecting to upstream
upstream prematurely closed connection while reading response header from upstream
recv() failed (104: Connection reset by peer) while reading response header from upstream
no live upstreams while connecting to upstream, upstream: "http://app_pool/"
upstream sent too big header while reading response header from upstream

04How do I check whether the upstream is healthy?

Test each hop from the inside out. These commands only read state and are safe on a production server. Use --resolve rather than the bare IP address: it sends the real hostname in both the Host header and the TLS server name, so the origin picks the same virtual host and certificate the proxy gets.

If step 1 fails, the application is the problem. If step 1 works but step 2 fails, look at the origin firewall, certificate or virtual host. If both work and the edge still returns 502, the edge is blocked or points at the wrong origin address.

# 1. the application port, on the server itself
curl -sv -o /dev/null -H 'Host: example.com' http://127.0.0.1:8000/

# 2. the origin from outside, bypassing the CDN, with the real hostname and SNI
curl -sv -o /dev/null --resolve example.com:443:203.0.113.10 https://example.com/

# 3. what is listening: TCP ports and Unix sockets
ss -ltnp | grep -E ':(80|443|8000|9000)\b'
ss -lxp | grep php

# 4. is the service running, and what did it log?
systemctl status php8.2-fpm
journalctl -u php8.2-fpm --since '-15 min'

# 5. did the kernel kill a worker for lack of memory?
journalctl -k --since '-1 hour' | grep -i 'out of memory'

05Why do 502s appear behind a CDN or WAF?

Behind a CDN or a web application firewall, the edge is the gateway. It returns a 502, or a provider-specific 5xx code such as Cloudflare's 520 for an empty or invalid origin response, whenever it cannot get a valid response from your origin, and the origin can be perfectly healthy for direct visitors while still failing for the edge.

The most common reason is the origin's own firewall. Once a proxy is in front, all traffic arrives from a small set of proxy addresses, so fail2ban, per-IP connection limits or a host's abuse filter can mistake the edge for an attacker and block it. A firewall that rejects the connection produces an instant refused connection and a 502; one that silently drops packets produces a timeout instead. Cloudflare's documentation, for example, names blocked or rate-limited Cloudflare addresses as the most common cause of its 522 connection-timeout error.

The fix is not to open everything. Allow the provider's published ranges, exempt them from per-IP limits, and keep everything else closed, so attackers cannot reach the origin address directly.

• Allow the provider's published ranges on ports 80 and 443, and keep the list current
• Exempt those ranges from fail2ban and per-IP limits on the origin
• Serve a valid certificate for the hostname if the edge verifies it
• Recheck the origin address configured at the provider after any migration

06How to fix a 502, cause by cause

Restarting the upstream clears most 502s for a while, but it does not explain why the worker died. Read the logs from just before the restart first, then fix the cause.

On nginx versions before 1.29.7, upstream keepalive stays off unless you add the keepalive directive, set proxy_http_version 1.1 and clear the Connection header, as below; from 1.29.7 those are the defaults. Either way, the idle timeout on the proxy side must be shorter than the application's.

• Crashed service: restart it, find the crash in its log, and set Restart=on-failure in the systemd unit
• Socket path changed after a PHP upgrade: point fastcgi_pass at the socket ss -lxp shows
• Permission denied: set listen.owner and listen.group in the pool file to the web server user
• Workers killed by timeouts: Gunicorn kills a worker silent for longer than its timeout (30 seconds by default), PHP-FPM at request_terminate_timeout; fix the slow request instead
• Workers killed for memory: pm.max_children times the memory per child must fit in RAM
• 502s after idle periods: Node.js advertises a 5-second keep-alive timeout by default and Gunicorn's threaded and async workers 2 seconds (its sync worker does not keep connections open), so keep the proxy's idle keepalive timeout below that
• Headers too big: raise proxy_buffer_size, or set fewer cookies

upstream app {
    server 127.0.0.1:8000 max_fails=3 fail_timeout=10s;
    server 127.0.0.1:8001 max_fails=3 fail_timeout=10s;
    keepalive 16;
    keepalive_timeout 4s;      # shorter than the app's own idle timeout
}

server {
    server_name example.com;
    location / {
        proxy_pass http://app;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_buffer_size 16k;     # room for large Set-Cookie headers
        proxy_buffers 8 16k;
    }
}

07What can visitors do about a 502?

Very little, because the fault is on the server side. Wait a minute and reload, since many 502s come from a restart during a deploy, and try another network if you use a VPN or corporate proxy. When reporting it, include the time, the URL and any request ID on the error page, which lets the operator find the exact log line.

08Do 502 errors hurt SEO?

A short burst does not; a persistent one does. Google's documentation says 5xx responses make its crawlers slow down, indexed URLs are kept at first but eventually dropped if the errors continue, and crawling recovers once the server returns 2xx again. For planned work, a 503 with Retry-After is the correct signal; an HTTP flood that exhausts your workers is a reason to filter traffic in front of the origin.