Skip to content
WebsiteHosting.com

troubleshooting HTTP, TLS & web servers

HTTP 502 troubleshooting

Investigate a proxy 502 by separating upstream response failures from 404, 503 and 504 without risky restarts.

Sources checked · P0028

What it means

An HTTP 502 Bad Gateway means a gateway or proxy received an invalid response while attempting to fulfill a request from an upstream server. It differs from a DNS timeout and from a 504 gateway timeout; the initial visible status does not prove the upstream application is the root cause. Compare proxy and upstream evidence. HTTP status semantics

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.

Investigate an upstream failure

Correlate gateway and upstream observations before making one narrow correction.

Simulation
Cause not established by a status code alone

A proxy-generated 502 is distinct from an application returning a valid 404. Keep the request, timestamp and request ID together.

Investigate an upstream failure: current state
ItemState / resultWhy it matters
clientNot observedRead-only evidence before any correction.
logNot observedRead-only evidence before any correction.
listenerNot observedRead-only evidence before any correction.
protocolNot observedRead-only evidence before any correction.
Investigate an upstream failure: local inputs and actions

Invented logs and outcomes. No service restarts, connections or server changes.

About this model

The declared gateway maps connection refusal and this protocol failure to 502, and this timeout to 504. Real products can map failures differently. A status code alone does not identify the root cause. The successful /health control is separate from the original /api/items request.

Read the article’s primary sources for protocol rules and implementation-specific limits. This scene has no network access.

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.

Incident fixtureEvidence to distinguish itNarrow correction in the rehearsal
Wrong upstream portRefusal at the selected port; app listens elsewhereCorrect that target port
Protocol mismatchProxy expects HTTPS, fixture listener speaks HTTPAlign transport with the declared service design
Configured timeoutClient sees 504 under this fixture's policyRestore the demonstrated timely service path

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.

Gateway reachable, upstream exchange invalid

A visitor reaches the public reverse proxy over HTTPS; the proxy selects an upstream but receives a malformed response or experiences an upstream protocol failure that it maps to 502. The public TLS connection could be fully valid while the internal exchange fails. Contrast a configured route to the wrong upstream port: depending on proxy behavior, an immediate connection refusal may also become a gateway error, but the exact mapping is implementation-specific. A slow upstream that never responds can instead produce 504 under suitable conditions. The simulated diagnosis shows candidate evidence, not an assertion that a particular production 502 has been repaired. Caddy proxy Gateway codes

In practice

Collect the first proxy-side error at a known timestamp, the chosen upstream address/port/protocol and corresponding upstream logs or health result, using authorized read-only access. Distinguish connection establishment, TLS to upstream, HTTP parsing and timeout. Stop before restarting or changing the whole proxy fleet merely because one 502 appeared. Any narrow authorized correction needs the old configuration and a repeat of the original public request.

Key takeaways

Treat 502 as evidence about the gateway’s attempt to use an upstream, not as an automatic diagnosis of one server. Fix the first supported failed dependency and retest from the original client-facing route.

Frequently asked questions

Editorial questions, answered from the sources listed for this article.

Does 502 prove that DNS failed?

No. A gateway can emit 502 after an HTTP-level failure while DNS resolution succeeds. Check the chosen upstream and proxy error evidence.

Is 502 the same as 504?

No. 504 relates to a gateway not receiving a timely upstream response, while 502 concerns an invalid response; actual proxy error mapping can be implementation-specific.

Can upstream TLS verification affect a reverse proxy?

Yes. An upstream connection with TLS can fail certificate or identity validation independently of the public connection. Disabling verification is not the standard fix.

Will restarting the proxy necessarily repair 502?

No. A wrong upstream route, unavailable service or protocol mismatch can remain after restart. Identify the failed dependency first.

Sources & model boundaries

Primary references used for this explanation. The interactive example is an educational model, not a live check.

  1. RFC 9110 — HTTP Semantics

    Sections 6, 8, 9 and 15. HTTP messages, methods, representations and status codes.

    Checked .

  2. Caddy Documentation — reverse_proxy

    Upstreams, load balancing, headers, transport and health checks. Reverse proxy upstream selection, forwarded headers, optional TLS transport and health checks.

    Checked .

  3. RFC 9525 — Service Identity in TLS

    Sections 3–6. TLS server name and certificate identity verification.

    Checked .

  4. RFC 9846 — The Transport Layer Security (TLS) Protocol Version 1.3

    TLS 1.3 security properties and connection boundaries; verified erratum 9040 reviewed, version negotiation not modeled. TLS 1.3 confidentiality, integrity and authentication boundaries. Obsoletes RFC 8446; the scene is not a handshake or version-negotiation implementation.

    Checked .