What is a 502 Bad Gateway error, and how do you fix it?

A 502 Bad Gateway means a server in the middle got a bad answer, or none, from the server behind it. The causes, and fixes for visitors and site owners.

1. The short answer

A 502 Bad Gateway error means a server in the middle, such as a proxy, load balancer or CDN, tried to fetch the page from the server behind it and got an invalid response, or no response at all. The problem is between the website's own servers, not your device or connection. Most often the app behind the proxy has crashed, is restarting, or isn't listening where the proxy expects it.

502 is an HTTP status code. Codes in the 500s mean the server side failed, unlike a 404, where the server worked fine but the page wasn't there.

2. Why there's a gateway at all

Most sites aren't one server. A request usually passes through a chain:

• your browser;
• a CDN or firewall in front of the site, such as Cloudflare;
• a proxy or load balancer, such as nginx, Traefik or a cloud load balancer;
• the app itself: Node.js, PHP-FPM, Python and so on.

Each layer passes the request on to the next and relays the answer back. When one layer can't get a usable answer from the next, it says so with a 502. The page you see usually comes from the layer that noticed: a plain nginx page saying "502 Bad Gateway", or a CDN's branded error page that shows which hop failed.

3. 502 vs 500, 503 and 504

• 500 Internal Server Error: the app itself ran and failed, often an unhandled error in the code.
• 502 Bad Gateway: the proxy couldn't get a valid answer from the app. Connection refused, connection dropped, or a garbled response.
• 503 Service Unavailable: the service isn't taking requests right now, because it's overloaded or in maintenance.
• 504 Gateway Timeout: the proxy reached the app, but the app took too long to answer.

Cloudflare adds its own codes in the 520s for problems reaching a site's server, such as 521 (the server refused the connection) and 524 (it took too long). They're close cousins of 502 and 504.

4. What to do as a visitor

1. Wait a minute and refresh. Many 502s come from an app restarting and clear on their own.
2. Check whether it's just you: try another browser, your phone on mobile data, or ask someone else.
3. Look at the site's status page or social accounts for an outage notice.
4. If it lasts, tell the site owner, with the time and the page.

Clearing your cache or changing DNS rarely helps with a 502, because the error comes from the site's servers. It's worth a try only if the site recently moved and your device might be holding an old address.

5. Common causes for site owners

• The app crashed or won't start. An error on startup, a missing environment variable or a database it can't reach. The proxy has nothing to talk to.
• The app is listening on the wrong port or address. It's running, but on port 8080 when the proxy expects 3000, or only on localhost when the proxy connects from outside its container.
• The app is restarting. During a deploy, there's a moment with nothing to answer, unless the host only switches traffic once the new version is healthy.
• Out of memory. The system kills the app process, and requests in flight fail.
• The app closes connections early or sends a malformed response, for example headers too large for the proxy.
• PHP-FPM or another backend is overloaded and refuses new connections.
• A firewall between the proxy and the app blocks the connection.
• DNS for the backend is wrong. The proxy looks up the app server by name and gets an old or missing address.

6. How to fix it, step by step

1. Read the logs first. The app's own logs usually show the crash or error. The proxy's error log says why it gave up, for example connect() failed (111: Connection refused) in nginx.
2. Check the app is running and isn't restarting in a loop.
3. Check the port and address. In Node, listen on process.env.PORT and on all addresses (0.0.0.0), not just localhost.
4. Check the settings it needs to start, like environment variables and the database connection.
5. Check memory. If it's being killed for using too much, reduce what it holds in memory or give it more.
6. Roll back. If the 502 started with a deploy, return to the previous version while you find the cause.

// A Node server that a proxy can reach
const port = process.env.PORT || 3000;
app.listen(port, "0.0.0.0");

7. On a Cloudzyro site

On Cloudzyro Sites & Apps, a new version only goes live after it starts and its home page answers. If it crashes on start or doesn't answer on the port in PORT (3000), the deploy fails, the console says why in plain words, and the previous version keeps running, so visitors aren't affected. The failed deploy guide covers each reason, including Crashed on start and Wrong port.

If visitors see an error on your own domain while the cloudzyro.app address works, look at the domain's DNS and certificate: the site's Domains tab says what it found, and the domain troubleshooting guide explains each message. Pages that take more than 125 seconds to answer get a timeout error from Cloudflare, which sits in front of every Cloudzyro site, so move slow work into the background. And if the problem is on our side, it shows on the status page.

New to hosting an app? How to host a website covers the basics.

8. A worked example

A developer moves a Node.js API to a new server behind nginx. The site shows "502 Bad Gateway".

1. nginx's error log says connect() failed (111: Connection refused) while connecting to upstream for http://127.0.0.1:3000.
2. curl -I http://127.0.0.1:3000 on the server fails too, so nothing is listening there.
3. The app's logs show it started on port 8080: the new server sets PORT=8080, and nginx still points at 3000.
4. She makes nginx and the app agree on one port, reloads nginx, and the 502 is gone.

9. How to check

# The status code and which server answered
curl -I https://www.example.com

# On the server: does the app answer directly?
curl -I http://127.0.0.1:3000

# nginx's recent errors
sudo tail -n 50 /var/log/nginx/error.log

The server: header in the response often tells you which layer sent the 502 (for example cloudflare or nginx), which narrows down where to look. If the app answers directly but not through the proxy, the problem is the proxy's settings or the network between them.

10. Sources

• RFC 9110, section 15.6.3: 502 Bad Gateway
• MDN: 502 Bad Gateway
• Cloudflare: Troubleshooting Cloudflare 5xx errors
• What is a 404 error?