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

Simulation — locate the failed proxy-to-upstream hop. Observe the client response, proxy log, listener and expected protocol before selecting a correction. Retest original request checks both the original route and a separate control route after a supported local change.

The initial fixture sends the proxy to port 9000 while the application listens on 8000. A 502 alone is not enough to prove that mismatch: compare the selected target, refusal log, listener and protocol first. Only then apply the port correction. The result remains “correction applied” until the original request is retested.

The protocol fixture is not a recommendation to downgrade a real HTTPS service: it represents an already declared internal HTTP design with a mismatched proxy setting. A real certificate identity or trust failure needs repair of that condition, not a verification bypass. The timeout fixture deliberately uses 504, so a successful exercise cannot blur it into 502. Status distinctions TLS verification

Applying a correction before the required observations, applying the wrong correction or applying twice stops. Reset removes the observations and correction and restores the original port incident. These are invented logs and deterministic transitions, not a health check, shell command, Caddy reload or proof about a deployed service.

Environment and stop conditions

The operational sequence below assumes an authorized operator with read-only access to the relevant proxy/application observations and the current approved service design. Keep production secrets, request credentials and personal bodies out of diagnostic notes. Determine which deployment and timestamp each observation describes before comparing them.

Stop when the selected upstream or protocol is unknown, logs do not correspond to the same request, or the proposed repair requires an unapproved firewall, identity or trust change. Do not bypass certificate verification, restart every service or replace the original URL simply to obtain a green result. Preserve the prior approved target/configuration and release before a narrow repair. If verification fails, restore that known configuration through the established deployment process and retain the failed evidence.

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.

Key takeaways

Treat 502 as a reason to inspect the selected upstream, not as a universal root cause. Match the original public request to the proxy's actual evidence, make one authorized repair, and retest the original and control routes. A direct upstream response alone does not verify the public path.