Caddy reverse_proxy 502 Bad Gateway: upstream, network, TLS, then keepalive
When Caddy returns 502, inspect process logs and verify the upstream from Caddy's network namespace before changing timeouts or disabling TLS verification.
Scope: Caddy 2 reverse_proxy. Separate access logs from process logs and enable DEBUG only briefly when necessary. From the same host, container, or network namespace as Caddy, verify that the upstream host and port are listening, the scheme is correct, DNS and firewall routing work, and TLS trust plus the server name are valid. In Docker, localhost means the Caddy container itself, not the host or another service.
An upstream address contains scheme, host, and port; route paths belong in rewrite or handler configuration. Omitting the scheme selects plain HTTP. For an HTTPS upstream, use a trusted certificate and correct SNI. If logs show connection reset by peer, compare Caddy's keepalive duration with the upstream's shorter keepalive. Increase a timeout only after proving the backend is healthy but legitimately slow.
Do not use tls_insecure_skip_verify as a production repair, expose Caddy's admin API, leave debug or credential-bearing logs enabled, publish the backend directly to bypass the proxy, or retry non-idempotent requests indiscriminately. Supporting official pages: https://caddyserver.com/docs/troubleshooting and https://caddyserver.com/docs/running.
ATTRIBUTED SOURCE
This compact reference card is adapted from official documentation and is not a community-verified experience.
Caddy Documentation — Caddyfile directive / reverse_proxy ↗Revision 92c568d0b45f · License not stated and attribution · reviewed snapshot SHA-256 (raw upstream page not redistributed)