中文
devexamples
← Debugging Guides

阅读中文版本

HTTP 502 Bad Gateway — Proxy Cannot Reach the Upstream

Trace a 502 from the reverse proxy to the upstream service, distinguishing a down backend, a wrong address or port, a timeout, and an application crash.

intermediatedebugginghttpproxynginx

Symptoms

  • The browser receives 502 Bad Gateway while the application logs show no request
  • Intermittent 502s under load while direct requests to the backend succeed
  • The proxy error log mentions connect() failed, upstream timed out, or an invalid response

Possible causes

  • The upstream process is down, crashed, or listening on a different port or address
  • The proxy timeout is shorter than the upstream response time
  • DNS or service discovery returns a stale or unreachable address
  • The upstream closes the connection or returns malformed HTTP

Diagnosis steps

Read the proxy error log

tail -n 100 /var/log/nginx/error.log

Interpretation

Messages such as connection refused, no live upstreams, or upstream timed out distinguish a reachability problem from a slow response.

Call the upstream directly from the proxy host

curl -i --max-time 5 http://127.0.0.1:3000/healthz

Interpretation

If direct access fails, the problem is the upstream. If it succeeds, compare the proxy configuration and network path.

Confirm the listening address and port

ss -ltnp | grep 3000

Interpretation

A process listening only on 127.0.0.1 is unreachable from another container or host. Bind to the expected interface or fix the proxy target.

Root cause

The reverse proxy could not obtain a valid HTTP response from the upstream. The upstream may be unreachable, refused the connection, timed out, or returned an invalid response, so the proxy returns 502 instead of forwarding an incomplete result.

Fix

Restore the upstream process, correct the target address and port, align timeouts with measured latency, add health checks and retries only for safe requests, and ensure the upstream binds to the interface the proxy uses. Fix crashes revealed by upstream logs.

Risk note

Increasing timeouts can hide a saturated upstream without fixing it. Retrying non-idempotent requests through a proxy can duplicate side effects.

Verify the fix

Request the public URL and confirm 200 with the expected body. Check the proxy error log for new 502 entries during a load test, and verify the upstream health endpoint and connection count stay stable.

502 is a proxy-side verdict

The proxy received a request but could not get a usable response from the upstream. The application may have never seen the request. Start with the proxy error log, then test the upstream directly from the same host or network namespace.

tail -n 100 /var/log/nginx/error.log
curl -i --max-time 5 http://127.0.0.1:3000/healthz
ss -ltnp | grep 3000

Common messages map to different causes: connection refused means nothing is listening, upstream timed out means it is too slow, and upstream sent invalid header means the response was malformed.

Fix

  • Start or restart the upstream and fix the crash.
  • Correct proxy_pass target, port, and interface binding.
  • Set connect, send, and read timeouts based on measured latency.
  • Add a readiness check so the proxy does not route to an unready instance.
  • Only retry idempotent requests, and bound retries.

Verify

  • The public URL returns 200 with the expected content.
  • The proxy error log shows no new 502s during a load test.
  • The upstream health endpoint is green.
  • Upstream logs show the requests that the proxy forwards.
  • Timeouts and retries are documented and bounded.

If 502s appear only under load, measure upstream saturation and connection pool limits before changing proxy timeouts.