Introduction

A 502 Bad Gateway error means a proxy or gateway server received an invalid response from the upstream service it tried to contact. In practical terms, the front door is working, but the application server, origin, or network hop behind it is failing in a way that prevents a normal HTTP response.

Symptoms

  • Visitors see 502 Bad Gateway instead of the site or application page
  • The error appears only through Nginx, Cloudflare, or another reverse proxy
  • Static files may load while dynamic requests fail
  • The issue starts after a deploy, restart, config change, or traffic spike
  • Upstream logs show crashes, refused connections, or timeout-related errors

Common Causes

  • The upstream application process is down, restarting, or overloaded
  • The reverse proxy points to the wrong port, socket, or backend address
  • PHP-FPM, Node.js, or another app server is timing out or crashing before it returns a response
  • Firewall, container, or network rules block the proxy from reaching the upstream service
  • A deploy changed health checks, upstream targets, or proxy timeout settings without matching the app behavior

Step-by-Step Fix

  1. Confirm where the 502 is generated by checking the browser response headers, proxy error logs, and upstream application logs.
  2. Verify that the backend service is running and listening on the expected port or Unix socket.
  3. Test the upstream directly from the server or container network so you can separate app failure from proxy misconfiguration.
  4. Compare the reverse proxy configuration with the live backend address, protocol, and timeout values.
  5. If the app recently deployed, inspect startup logs for crashes, missing environment variables, failed migrations, or dependency errors.
  6. Check whether CPU, memory, connection limits, or worker exhaustion are causing the upstream to stop responding under load.
  7. Review firewall rules, security groups, container networking, and loopback bindings to ensure the proxy can actually reach the app.
  8. Reload or restart the affected proxy and upstream services only after correcting the broken target, process, or timeout issue.
  9. Re-test through the public hostname and monitor logs for several minutes to confirm the upstream stays healthy under normal traffic.