HTTP 502 troubleshooting

What it means

HTTP `502 Bad Gateway` indicates a server acting as a gateway or proxy received an invalid response from an upstream server while attempting to fulfill the request. In practice, operators often investigate upstream connection resets, malformed responses, address/port mismatches or TLS-to-upstream failures. A particular proxy may map some transport failures to 502 according to its implementation. Status semantics Proxy transport

A 502 is not the same as 404 Not Found (target not found), 503 Service Unavailable (temporary overload or maintenance), or 504 Gateway Timeout (gateway did not receive a timely upstream response). The code narrows the investigation, but does not identify one universal root cause.

Try it

Example — locate the failing connection in a fictional service path. This is not a live health check.

Visitor ---> public HTTPS proxy ---> app on internal port
              |                         |
              +--- 502 error <----------+ invalid/incomplete response

If the proxy can accept HTTPS and produce a 502, public DNS and client-facing TLS may already be working. The next question is what happened between the proxy and selected upstream. A browser screenshot of 502 alone cannot show whether that upstream is stopped, misconfigured or returning malformed data.

A safe investigation sequence

1. Record time, request hostname/path, response status and any harmless request or trace ID. Do not expose authentication headers or personal request bodies in support notes.
2. Check the approved provider/status monitoring system and read-only proxy logs. Identify the upstream selected and the actual transport error (connection refused, EOF, malformed HTTP, certificate failure or timeout).
3. Compare the upstream's documented listening address and port with its current health state and the proxy's routing configuration. Testing an internal endpoint must be authorized and performed within the normal access boundary.
4. If the proxy uses HTTPS to the upstream, inspect certificate identity and trust rather than disabling certificate verification. The TLS handshake can fail before any upstream HTTP response arrives. TLS service identity
5. Compare nearby good requests and the previous known-good deploy. Where several upstreams exist, inspect whether only one is affected. Check resource pressure and application logs without indiscriminately restarting services.

Correct and verify

Choose the smallest reviewed repair at the proven layer: restore a healthy upstream release, correct a wrong route/port using the normal deployment process, or repair the upstream's certificate configuration. Keep an explicit rollback to the last known-good state. Repeatedly reloading Caddy, changing firewalls or bypassing TLS validation without evidence can make an incident worse.

After the fix, retest the original public route, an unrelated known-good route and relevant upstream health checks. A passing direct upstream test is not sufficient: the public proxy path must return the intended HTTP response too.

In practice

Use Reverse proxy to locate the hop, HTTPS and TLS for certificate/transport boundaries, and HTTP 404 troubleshooting when the response is instead a missing target. A 502 is a diagnostic clue, not permission to restart production blindly.