Lorixen.
EN

502 Bad Gateway: find out why your proxy can't reach the app

Short answer: A 502 Bad Gateway means the server in front, such as nginx, a load balancer or a CDN, tried to reach your app and got an invalid response or none at all. The usual causes are the app process being down or restarting, the proxy pointing at the wrong port or socket, the app crashing on certain requests, or response headers too large for the proxy's buffer. Start with the proxy's error log: it almost always names the exact reason, such as "connection refused" or "upstream prematurely closed connection".

What 502 actually means

HTTP's specification, RFC 9110, defines 502 as the status a server returns when, acting as a gateway or proxy, it received an invalid response from an inbound server it accessed while trying to fulfil the request. In plain terms: the front door is fine, but whatever it forwards requests to didn't answer properly.

That distinguishes it from its neighbours:

  • 504 Gateway Timeout: the proxy waited and got no timely response. The app is slow.
  • 503 Service Unavailable: something deliberately reports it can't serve right now, such as maintenance mode or an overloaded upstream.
  • 502 Bad Gateway: the conversation with the app failed outright.

Because many layers can act as a gateway, a CDN in front of a load balancer in front of nginx in front of your app, the first job is working out which layer produced the 502. Error pages often say: a CDN-branded error page points at the CDN failing to reach your origin, while a plain nginx page means nginx couldn't reach the app.

Read the error log first

On nginx, the error log usually sits in /var/log/nginx/error.log. Look for lines at the time of the failures. Typical messages and what they point to:

  • "connect() failed (111: Connection refused)": nothing is listening on the address nginx is using. The app is down, starting up, or on a different port.
  • "connect() to unix:/run/app.sock failed (2: No such file or directory)" or a permission error on a socket: the app isn't creating the socket, or nginx can't access it.
  • "upstream prematurely closed connection while reading response header": the app accepted the request and then died or dropped the connection, often a crash, a worker killed for using too much memory, or a request hitting a bug.
  • "upstream sent too big header while reading response header": the app's response headers, often large cookies or many redirects' worth of headers, exceed the proxy's buffer.
  • "no live upstreams": every backend in the upstream group has been marked as failed.

Your app's own logs, and the system log for out-of-memory kills, fill in the rest.

Common causes and fixes

The app isn't running. Check the service status and restart it. If it keeps stopping, the app's logs will show why: a missing environment variable after a deploy, a failed database connection, a syntax error.

Wrong address or port. After a migration or config change, nginx's proxy_pass or upstream may point at the old port, or the app may now listen only on 127.0.0.1 while nginx calls a container name or different address. Make both sides agree.

Deploy restarts. If 502s cluster at deploy time, the app is briefly unavailable while restarting. Use your process manager's graceful reload, run more than one instance and restart them one at a time, or have a health check gate traffic until the new process is ready.

Crashes on specific requests. If only some pages fail, look for errors in the app's log on those routes. A worker that runs out of memory processing a large export, for example, dies mid-request and nginx reports a premature close.

Header buffer too small. For "too big header" errors, either reduce what the app sends, often by trimming cookies, or raise nginx's proxy_buffer_size and proxy_buffers modestly. Fixing the cause is better than inflating buffers.

Keep-alive mismatches. When nginx reuses connections to the app, the app's idle timeout should be longer than nginx's, or nginx may send a request on a connection the app has just closed. Intermittent 502s under light load can point to this.

PHP-FPM and similar pools. For PHP sites, the pool may be out of workers or the socket path may have changed after an upgrade. The pool's own log names the issue.

When the CDN shows the 502

If your CDN reports a bad gateway, check whether it can reach your origin at all: firewall rules that block the CDN's addresses, an expired or mismatched certificate on the origin when the CDN connects over HTTPS, or the origin server being down. Test by requesting the origin directly, bypassing the CDN, from another machine.

Make the next 502 easier

  • Health checks: have the load balancer or orchestrator check an endpoint that confirms the app can serve, and stop routing to instances that fail.
  • Alerts on 5xx rates: a rise in 502s should reach someone before customers report it.
  • A friendly error page: configure the proxy to show a branded page with a short message instead of a bare error.
  • Log request IDs: pass an ID from the proxy to the app so you can match a failing request in both logs.

A worked example

Consider a hypothetical Dunedin bookshop whose website returned intermittent 502s every evening. nginx's error log showed "upstream prematurely closed connection" at the same times, and the system log showed the app's worker being killed for memory use. An evening job generating stock reports ran inside the web process. The developer moved the job to a separate scheduled worker, set a memory limit on it, and added an alert on 502 rates. The evening errors stopped.

FAQ

Is a 502 my host's fault?

Sometimes, but usually it's between the proxy and your app on your own server. Check the logs before contacting the host.

Will clearing my browser cache fix it?

Rarely. A 502 comes from the server side. Reloading may work if the app was briefly restarting.

Does a 502 hurt SEO?

Brief, occasional errors are common. Persistent server errors can affect crawling, so fix recurring ones.

Why do I only see 502s on one page?

That page likely triggers a crash, a slow external call or oversized headers. Check the app log for that route.

If your site keeps throwing 502 errors, tell us how it's hosted and we'll help find the layer that's failing.

Sources

WhatsAppBook a call