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

Which layer sent the 502?

The error page itself is the first clue. A plain page reading "502 Bad Gateway" with "nginx" underneath came from nginx, which could not get a valid response from the application. Load balancers and CDNs show their own styled pages. Hosting control panels sometimes replace the page with a branded one.

The response headers add more. The HTTP header checker lists every header the server returned, and the server, via and CDN-specific headers show which systems the response passed through. The uptime check confirms the error from outside your network and names the failing stage, which separates a 5xx response from a DNS, connection or TLS failure.

Common causes

Behind most 502s is an application layer that is down, unreachable or misbehaving:

• The application process crashed or stopped. PHP-FPM, a Node.js app or a Python app server is not running, so the proxy's connection is refused.
• The proxy points at the wrong address. After a PHP version upgrade, the PHP-FPM socket path often changes (for example from php8.2-fpm.sock to php8.3-fpm.sock) while the nginx configuration still names the old one. The same happens when an app moves to a different port.
• The application ran out of workers or memory. PHP-FPM logs a warning when it reaches its pm.max_children limit, and the operating system's out-of-memory killer can terminate processes under heavy load.
• The application returned something the proxy rejects, such as response headers larger than the proxy's buffers. nginx logs this as "upstream sent too big header".
• The application closed the connection mid-response, for example after a fatal error or a worker being killed for running too long.
• A firewall or security rule blocks traffic between the proxy and the application server, common when they run on separate machines.

502 errors behind Cloudflare and other CDNs

Behind a CDN there is one more layer. Cloudflare reports most problems reaching your server with its own codes: 520 for an unexpected response, 521 when the web server refuses the connection, 522 when the connection times out, 523 when the origin is unreachable, 524 when the origin is too slow to answer, and 525 or 526 for TLS problems between Cloudflare and the origin.

A plain 502 or 504 behind Cloudflare usually reflects your origin's own error passing through, though Cloudflare documents rare cases where it generates one itself. Either way, start at the origin: test it directly by sending a request to the origin IP address with the correct hostname, for example with curl --resolve, and read the origin's error log.

How to fix a 502 as the site owner

Follow the request inward and check each hand-off:

1. 1Confirm the error from outside with the uptime check, and note whether it is constant or intermittent. Constant points at a stopped service or wrong configuration; intermittent points at capacity.
2. 2Read the web server's error log at the time of the error. In nginx, "connect() failed (111: Connection refused) while connecting to upstream" means nothing is listening, "No such file or directory" on a socket means the path is wrong, and "upstream prematurely closed connection" means the application died mid-request.
3. 3Check that the application service is running, and restart it if not (for example, systemctl restart php8.3-fpm or your process manager's restart command).
4. 4Compare the address in the proxy configuration (fastcgi_pass, proxy_pass or ProxyPass) with the socket or port the application actually listens on.
5. 5Check memory and worker limits. Look for out-of-memory kills in the system log, and for PHP-FPM max_children warnings in its log. Raise limits only as far as the server's memory allows.
6. 6If the log mentions header size, increase proxy_buffer_size or fastcgi_buffer_size in nginx.
7. 7Roll back the most recent change if the errors started after a deploy, plugin update or configuration edit. On WordPress, renaming the plugins folder over SFTP deactivates every plugin at once for testing.

Intermittent 502s

A 502 that appears on a small share of requests, with no crash in the logs, often comes from a keep-alive mismatch. A load balancer or proxy keeps idle connections to the application open for reuse. If the application closes idle connections sooner than the proxy expects, the proxy occasionally sends a request down a connection the application has just closed, and the visitor gets a 502. The fix is to make the application's keep-alive timeout longer than the proxy's idle timeout; Node.js servers behind cloud load balancers are a frequent example.

Other intermittent patterns are easier to spot by time. 502s that cluster during deploys mean old processes stop before new ones are ready, which a rolling or graceful restart avoids. 502s that cluster at traffic peaks point at worker or memory limits.

What visitors can do

A 502 is almost never caused by the visitor. Wait a minute and reload, since many 502s come from a service restarting or a short overload. If it persists, check whether the site has a status page or social account reporting an outage.

Clearing the browser cache or switching browsers rarely helps, but trying another network can rule out a corporate proxy or VPN that is itself acting as the failing gateway.

Preventing repeat 502s

Run the application under a supervisor that restarts it automatically if it crashes, such as systemd with a restart policy or a Node.js process manager. Size worker pools to the memory the server actually has, so a traffic spike queues requests instead of triggering the out-of-memory killer.

After every PHP upgrade, server migration or proxy configuration change, check that the proxy still points at the right socket or port. Pair that with external monitoring so a crashed application is noticed in minutes rather than when visitors complain.