Docker Container Passes Healthcheck but Reverse Proxy Returns 502

Before replacing hardware or resetting an account, identify exactly when this happens: Docker reports a healthy container while browser requests receive 502. The aim is to identify the first failing dependency, apply only an appropriate supported change and demonstrate that the original operation works again. The tests are tied to real device behavior and supported configuration, not assumptions about a future error code.

Identify the failure pattern

Docker reports a healthy container while browser requests receive 502. Record whether this happens every time or only after an update, a network change or a restart. Check whether another device or a second authorized account exhibits the same behavior: that distinction can prevent an unnecessary device-wide repair.

Likely cause and failure boundary

The proxy may target the wrong internal port or network even when healthcheck succeeds. Server troubleshooting works best with the specific failing route, its deployment version and the earliest meaningful error. A healthy process does not establish correct network exposure or configuration. Check application, proxy and dependency logs together and choose a reversible test.

For this Docker case, the initial explanation is only a working hypothesis: The proxy may target the wrong internal port or network even when healthcheck succeeds. Test it against the first observation, compare published service port with the container's actual listening port. If those results do not support the suspected cause, compare the second and third checks rather than treating an update or a network connection as proof of a specific fault.

Before making changes

Work in staging or during an approved maintenance window where possible. Take a config backup and do not print passwords, tokens or private customer data. Do not expose backend services publicly just to bypass the reverse proxy.

• Record: application versions, sanitized server logs, the original setting and request correlation data.
• Make the first check read-only: Compare published service port with the container's actual listening port.
• Define success in advance: Proxy returns the expected application response and healthcheck stays healthy.

Decision guide: interpreting the checks

If a standalone service check passes yet the end-user request fails, a proxy, policy or downstream dependency could be responsible. Follow the first failed hop: Compare published service port with the container's actual listening port. Use an approved network test from the proxy container to the upstream name.

If the first check does not match the expected state, correct that dependency before proceeding. If the first check is normal but the second differs from a working baseline, focus on the second layer instead. If both appear normal, use the third test to distinguish the remaining configuration or device-specific path: Inspect proxy upstream configuration and container logs for refused connections.

Common mistakes to avoid

• Do not expose backend services publicly just to bypass the reverse proxy.
• Changing several settings at once makes it impossible to know which adjustment mattered. Repeat the original test after each approved change.
• Assuming an online or connected indicator proves that Docker can complete the required operation.

Optional read-only diagnostic example

For Docker, this command can provide a narrow starting observation before attempting the following test: Compare published service port with the container's actual listening port. Run it only where its runtime and permissions are supported; the output is evidence, not a repair. Replace sample hostnames with approved test values.

docker compose ps

How to verify the fix

Proxy returns the expected application response and healthcheck stays healthy. Re-run the same original action with the same authorized account, device or file, and compare the result with the recorded baseline. Do not declare success just because a status indicator changes color or a test utility finishes without error.

If the issue was intermittent, repeat the relevant Docker operation at several short intervals and record times. Then perform a routine reconnect or restart only if it was associated with the original failure. In this case the confirmation is specific: Proxy returns the expected application response and healthcheck stays healthy. If only one configuration works, document that limit and check inspect proxy upstream configuration and container logs for refused connections. before extending the conclusion to other users or devices.

If the problem continues

If Docker continues to show this behavior, stop making broad changes. Do not expose backend services publicly just to bypass the reverse proxy. Restore test settings that did not help, preserve the exact observation from compare published service port with the container's actual listening port. and contact the relevant device vendor, service provider or organizational administrator. Include version numbers, error IDs, sanitized config differences and a reproducible request from staging.

Prevent the problem from returning

Keep a note of the exact Docker configuration that produced the working result: Proxy returns the expected application response and healthcheck stays healthy. Recheck the same operation after deployment, dependency, security policy and host-runtime changes. For this failure, the quickest future comparison is compare published service port with the container's actual listening port. Preserve supported settings and use vendor-approved maintenance rather than accumulating unverified resets.