Caddy Reverse Proxy 502 for One Upstream — Caddy returns 502 for one proxied backend while others work. This guide focuses on separating the immediate failure from the underlying cause, with checks selected for the affected product instead of generic resets.
Recognize the failure and narrow its scope
Review upstream address, health status and scheme in Caddy logs. Start with the smallest reproducible example: one device, one file, one account or one transaction where possible. If the problem occurs only in a particular environment, that boundary guides the repair more reliably than the wording alone.
Test backend from proxy host with correct Host and TLS settings. Save the result, version number and time of the failure so a later test can be compared against the same conditions. A successful test in a different environment does not prove the original environment is fixed.
Before changing the system
Risk to avoid: Avoid exposing private backend directly to the internet. Capture a timestamped request ID and inspect edge, reverse-proxy and origin layers separately before changing production configuration.
The guided methods begin with observation and reversible changes. Use the advanced checks only when the earlier test points to the corresponding subsystem or when you have administrative authorization.
Step-by-Step Troubleshooting
Use Beginner checks before Advanced methods. Record one change at a time, preserve evidence and use the device or software vendor documentation.
Confirm the failure and its boundaries
Caddy returns 502 for one proxied backend while others work. Review upstream address, health status and scheme in Caddy logs. Capture the affected model or software version, exact message and time. Compare only one factor at a time so a successful test has a clear explanation.
Collect the discriminating evidence
Test backend from proxy host with correct Host and TLS settings. Write down the finding and compare it with a known-good device, account, application or connection where that comparison is safe. A different result points to the layer worth investigating.
Apply the least disruptive corrective action
Correct upstream port or scheme instead of disabling TLS. Re-test immediately before taking another action. If the result does not change, return the modified setting to its original value whenever practical.
Run the same success test again
Route serves expected backend with reliable HTTP status. Test the exact action that failed rather than a loosely related function. If this is intermittent, repeat under the original load or connectivity conditions.
Trace the specific failing subsystem
Test backend from proxy host with correct Host and TLS settings. Check relevant application, device, service or server logs only for this failure window. Compare timestamps and avoid treating unrelated warnings as the root cause.
Investigate the supported advanced repair
Inspect trusted CA and transport timeouts in Caddy config. Perform this only after the first two checks support that hypothesis. Use official documentation for the installed release and record previous values before editing configuration.
Preserve the rollback and security boundary
Avoid exposing private backend directly to the internet. Document what changed, who authorized it and how to reverse it. If backups or account ownership cannot be verified, stop before destructive work.
Confirm recovery with a repeatable test
Route serves expected backend with reliable HTTP status. Repeat after reconnecting, restarting the relevant service, or beginning a new session when that is part of the original failure. Record the new logs and compare them with the baseline.
Interpret the test results
| What you observe | Likely direction | What to do next |
|---|---|---|
| The issue changes under the comparison test. | Review upstream address, health status and scheme in Caddy logs. | Document which factor changed and retest the same operation. |
| The symptom persists and diagnostics show a specific fault. | Test backend from proxy host with correct Host and TLS settings. | Inspect trusted CA and transport timeouts in Caddy config. |
| A safe correction seems to resolve the issue. | Correct upstream port or scheme instead of disabling TLS. | Route serves expected backend with reliable HTTP status. |
Use the table as a decision path, not a list of actions to perform all at once. If caddy returns 502 for one proxied backend while others work, preserve the exact error and scope. If the comparison changes the outcome, investigate the differing configuration before touching unrelated components.
How to verify the repair worked
Route serves expected backend with reliable HTTP status. Repeat the same operation that originally failed, not merely a related smoke test. Where possible, perform a second run after reopening the application, reconnecting the device, or restarting the relevant service. Check that the successful result persists and that no new warning or data inconsistency has appeared.
A single successful attempt is encouraging but insufficient for intermittent faults. Keep the comparison result and exact steps so the change can be reversed if another subsystem is affected.
Solution Checklist
When to stop and escalate
If the problem remains after the low-risk steps, the next supported diagnostic route is: Inspect trusted CA and transport timeouts in Caddy config. Stop if the procedure would affect sensitive credentials, erase data, change production permissions or require unsupported firmware actions. Provide a technician or administrator with the original symptom, comparison findings, relevant logs and changes already attempted.
Common questions
Should I reset the device or reinstall everything?
Not as an initial step. The first meaningful discriminator here is: Review upstream address, health status and scheme in Caddy logs. A broad reset can remove settings or local data while leaving a network, account, hardware or service-side problem untouched.
How do I know the problem has not simply disappeared temporarily?
Route serves expected backend with reliable HTTP status. Re-test under the same conditions that caused the failure. If it returns, collect the new diagnostic evidence before making another change.
Further reading
For supported options and version-specific menu paths, consult MDN HTTP documentation. The linked portal is general vendor documentation, not necessarily a page confirming this exact error code. Match instructions to the affected model and software version.