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

Most websites sit behind at least one proxy: nginx, a load balancer, Cloudflare, or an app platform’s router. The proxy forwards your request to the app. When that connection is refused, reset, or answered with garbage, the proxy returns 502 on the app’s behalf. It is one of the 5xx server errors, so the fault is on the server side, never in the visitor’s browser.

1. The app is down or restarting, often during a deploy or after a crash.
2. The app listens somewhere else: on a different port, or on localhost instead of 0.0.0.0, so the proxy cannot connect.
3. The app was killed mid-request, for example by an out-of-memory kill (exit code 137).
4. The app closed the connection early: a worker timeout, or a keep-alive timeout shorter than the proxy’s.
5. The app is overloaded and refuses new connections.

A 502 during a deploy or a restart usually clears within seconds to a few minutes. One that lasts longer means the app is not coming back by itself: check its logs and whether it is listening.

1. Check the app is running and has not just restarted.
2. Check the port and host the app listens on match what the proxy expects.
3. Read the app’s logs at the minute the 502s started: look for a crash, an out-of-memory kill or a timeout.
4. Check memory and CPU. A service at its limit drops connections.
5. Line up the timeouts. If the 502s come and go, make the app’s keep-alive and worker timeouts longer than the proxy’s.

nginx says why in its error log. The two lines you will see most:

connect() failed (111: Connection refused) while connecting to upstream
upstream prematurely closed connection while reading response header from upstream

The first means the app is down or on another port: check that proxy_pass points at the port the app listens on. The second means the app hung up mid-request, usually a crash or a worker timeout.

• Cloudflare: a 502 page with Cloudflare’s branding means Cloudflare itself had trouble; your origin’s own 502 shows without it. Connection problems with your origin show as Cloudflare’s 520 to 526 codes instead. Cloudflare 502 and 52x errors.
• Railway: “Application failed to respond” is Railway’s 502. Its edge proxy cannot reach your app, most often because of the port or the host binding. Railway 5xx errors.
• Render: a 502 means Render’s proxy could not talk to your process. Persistent 502s right after a deploy usually mean it is not bound to 0.0.0.0:$PORT. Render 502 errors.