LightAtom

502 Bad Gateway: What It Means and How to Fix It

A server acting as a gateway or proxy, such as a CDN, load balancer or nginx, got an invalid response from the server behind it. It's almost always a server-side problem.

502 Bad Gateway

The server you reached is a middleman (a proxy, CDN or load balancer). It forwarded your request to the real server behind it and got a broken or empty response back.

Quick checks

  • Reload after a minute: 502s are often brief, during deploys or restarts.
  • Check whether the site is down for everyone (its status page or social accounts).
  • Try another network or device to rule out a local proxy or VPN.

If you’re visiting the site

  1. Wait and reload

    1. Press ⌘R (Mac) or F5 (Windows) after a minute or two.
    2. A hard reload (⌘⇧R) skips cached copies of the error page.

  2. Rule out your side

    1. Disconnect VPNs and proxies; some corporate proxies return their own 502.
    2. Try another browser or a private window.
    3. Flush DNS on your Mac (sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder) in case the site recently moved.

If you run the site

  1. Check the upstream (application) server

    1. Is the app process running? Check systemctl status, Docker or your process manager, and look for crashes or out-of-memory kills.
    2. Does it listen where the proxy expects? Compare the proxy's proxy_pass or upstream address and port with the app's listening address.

  2. Read the proxy's error log

    1. nginx: /var/log/nginx/error.log shows lines like connect() failed (111: Connection refused) while connecting to upstream or upstream prematurely closed connection.
    2. Refused means the app isn't listening; prematurely closed means it crashed or hit a limit mid-request.

  3. Check limits and timeouts

    1. Large headers or cookies can exceed proxy buffers (proxy_buffer_size in nginx).
    2. PHP-FPM, Gunicorn and similar pools may be exhausted under load; raise workers or fix slow requests.

  4. Behind a CDN

    1. Cloudflare shows its own codes (520–526) for origin problems; check the origin directly, bypassing the CDN, to see if it answers.

Still not working?

Visitors can't fix a 502: it's between the site's own servers. If it persists for hours, contact the site.

Owners: test the upstream directly from the proxy host with curl -v http://127.0.0.1:PORT/ to separate an app failure from a proxy misconfiguration.

See what’s happening

For developers running a local reverse proxy, LightAtom's Ports view shows whether the upstream app is listening and on which address and port.

Frequently asked questions

Is 502 Bad Gateway my fault?

Almost never. It means the site's own servers can't talk to each other properly. Rarely, a corporate proxy or VPN returns a 502; try another network to check.

What is the difference between 502 and 504?

502 means the upstream server returned an invalid response or closed the connection. 504 means it didn't respond in time. Both come from a gateway or proxy.

How long does a 502 error last?

Usually seconds to minutes, during a restart or deployment. Longer outages mean the backend is down and needs the site's team to fix it.

Can clearing my cache fix a 502?

Only if your browser cached the error page. A hard reload (⌘⇧R) rules that out; otherwise the fix is on the server.

Related errors and tools

Related

LightAtom team

The people who build LightAtom, a network monitor for macOS.