Your site has two layers: a server in front (a "gateway" or proxy, such as nginx, a load balancer, or your host's router) and your app behind it. A 502 means the front server asked your app for the page and got no proper answer. Usually your app has crashed, never started, is listening on a different port or address from the one the front server expects, or answered with something broken.
What's the problem
Visitors get "502 Bad Gateway", often on a plain page that names nginx or your hosting provider. Sometimes it's every page, sometimes only now and then, or only under load.
Why it happens
The front server is working; it's reporting that the thing behind it isn't.
- The app isn't running. It crashed, ran out of memory, or failed on start, so there's nothing to answer.
- It's listening in the wrong place. The front server sends requests to one port, and the app is listening on another. Or the app listens only on
localhost, which inside a container or a separate machine means only itself, when it needs to listen on0.0.0.0. - A middle piece is down. On PHP sites, nginx hands requests to a separate PHP process (PHP-FPM). If that process isn't running, nginx returns a 502.
- It answered badly or too slowly. The app returned a malformed reply, or took longer than the front server was willing to wait.
How to fix it
- Check the app is actually running on your host's dashboard, or with your process manager on the server. If it isn't, its logs will say why it stopped.
- Read the app's logs around the time of the 502s.
- Check the front server's error log. For nginx it names the address it tried and the reason, such as "connection refused" or "upstream timed out".
- Match the port and address. The port the front server forwards to must be the port the app listens on. In containers, the app should listen on
0.0.0.0. - On PHP sites, check PHP-FPM is running and nginx points at the right socket or port.
- If 502s only happen under load, the app is running out of memory or connections. See how to make your app scale.
When to call Preventionlabs
If the app simply wasn't running or the port was wrong, you're done. Call us when it keeps falling over and nobody can say why, or when the whole setup (proxy, app, process manager, server) was put together by someone who's gone. A resurrection gets it running in your own hosting account, on infrastructure that adds capacity through settings, and hands it back with notes on how it all fits together.
Submit your project for a free assessmentFree assessment. $10,000 AUD flat to get it live, only if we take it on and you go ahead.
Sources
- MDN Web Docs: 502 Bad Gatewayweb reference
The HTTP 502 Bad Gateway server error response status code indicates that a server was acting as a gateway or proxy and that it received an invalid response from the upstream server.
- MDN Web Docs: 502 Bad Gatewayweb reference
There are many causes of 502 errors, and fixing such problems probably requires investigation by server owners or administrators.
- Render: Web Services: Port bindinghosting platform docs
Every Render web service must bind to a port on host 0.0.0.0 to serve HTTP requests.