Why Does a Reverse Proxy Return 502 After a Container Rebuild?

A reverse proxy returns 502 after a container rebuild when it can no longer open a valid connection to the rebuilt upstream.

Rebuilding can replace the container, assign a new address, detach or rename a Docker network, change the exposed port, restore an incomplete configuration, or start the proxy before the application is ready. The correct diagnosis begins with the proxy error log and follows the exact upstream address from proxy to container rather than restarting both services until the error temporarily disappears.

Confirm That the 502 Comes From Upstream Connection Failure

Request the affected domain once and record the timestamp, proxy status, upstream address, and complete error message. Distinguish connection refused, host not found, timeout, reset, TLS handshake failure, and invalid response.

A 502 means the proxy received no usable upstream response, but the error detail determines whether the target was absent, unreachable, not listening, or speaking the wrong protocol. A current NGINX troubleshooting guide notes that a rebuilt container can leave the proxy using an old backend address until name resolution or configuration is refreshed.

Test the application directly from the proxy host or proxy container using the logged upstream name, address, port, and protocol. If that direct request fails in the same way, keep the investigation between proxy and container rather than changing public DNS or certificates.

Compare the Upstream Target Before and After the Rebuild

Inspect the rebuilt container name, service name, internal IP, exposed port, published port, network aliases, and network attachments. Compare them with the proxy configuration and its last working target.

An nginx-proxy issue describes a rebuild that changed the application container IP while the proxy continued sending requests to the unreachable container upstream. The public domain stayed correct while only the private upstream identity changed.

Prefer a stable Compose service name or network alias over a container IP. If an IP is intentionally fixed, verify that the rebuilt service actually received it and that no other container now owns the address.

Verify the Proxy and App Still Share a Docker Network

List the networks attached to the proxy and application and confirm they share at least one user-defined network. A published host port does not automatically make the container name reachable from another isolated Docker network.

A Docker networking case found that moving a dependent service to the appropriate network immediately removed recurring 502 responses, demonstrating how an unreachable upstream path even when all containers remain running.

Attach services through Compose rather than one-off commands so the relationship survives rebuilds. Test DNS resolution and the upstream port from inside the proxy container after recreating the stack.

-15% OFF

ZimaBoard 2 - Mini Home Server for Your Big Idea

Single board computer zimaboard2

$339.00 - $519.00

Buy Now

Check the Internal Listener Port and Bind Address

Confirm the application is listening on the port the proxy uses and on an address reachable from the container network. Do not confuse a host-published port with the container’s internal listening port.

A proxy can connect only after the app binds beyond loopback. A service listening on 127.0.0.1 inside its own container is unavailable to the proxy even when a local health command succeeds.

Inspect the application log, socket list, and one direct request from the proxy container. If the port refuses connections, repair the app listener or configuration before adding retries or longer proxy timeouts.

Wait for Application Readiness Instead of Container Start

A rebuilt container can be running while migrations, database recovery, cache warm-up, or configuration generation still prevents the application from accepting requests. Compare the first 502 timestamp with health and startup logs.

A Grist troubleshooting discussion shows how Docker architecture, environment settings, and upstream readiness can combine into persistent container-side 502 failures after a rebuild.

Add a meaningful health check and make the proxy or dependent services wait for the operation clients need, not merely the existence of a process. Keep retries bounded so a permanently failed app does not look like a slow startup.

Refresh Proxy Resolution and Rebuild the Stable Path

Reload or recreate the proxy after the service name, network, port, and health state are correct. If the proxy resolves names only at startup, configure supported runtime resolution or a predictable restart order.

The ZimaSpace workflow for isolating a failing container dependency provides the adjacent diagnostic when the upstream repeatedly exits instead of staying healthy.

The repair is complete only when the proxy resolves the service name after another rebuild, reaches the intended internal port, waits through startup, and serves the domain without manual IP edits. Remove temporary direct-IP targets and undocumented network attachments after validation.