NGINX 502 with a Running Docker Container

A running container does not prove the reverse proxy can reach its application. A 502 usually means the proxy could not obtain an acceptable upstream response. Read the proxy error log and test the upstream from the proxy's own network environment.

Capture one failing request

Record timestamp, requested path, response status and a request identifier if available. Compare the proxy error with the application log at the same time.

The NGINX proxy reference documents upstream behavior and controls. Do not treat every 502 as a timeout; timeout symptoms and status handling can differ.

Avoid restarting every service before capturing the error. A restart may erase the conditions that explain an intermittent failure.

Test from the caller's location

If NGINX runs in a container, localhost inside NGINX normally points to that container. An application reachable at localhost on the host may need a different address from the proxy.

Docker's Compose networking guide explains shared-network service addressing. Verify the service name, container port and network membership.

Check the application's bind address as well. A process listening only on its own loopback interface may not accept connections from another container.

Match symptoms to evidence

Proxy log or observation	Investigation
Connection refused	Wrong port, listener absent or rejected
Host cannot resolve	Service name or DNS configuration
Upstream closes early	Application crash or protocol mismatch
TLS handshake failure	HTTP/HTTPS mismatch or certificate setup
Failures during startup	Readiness and deployment ordering

These are investigation directions, not guaranteed diagnoses. Preserve the exact error text with sensitive values redacted.

Check the protocol and path

An HTTP upstream configured as HTTPS, or the reverse, can fail even though a port is open. A healthy root endpoint also does not prove the specific application route works.

Send the same harmless path directly to the upstream from the proxy environment. Compare headers and host expectations where the application uses virtual-host routing.

If the application is restarting under load, investigate memory, process exits and dependency failures rather than only changing proxy settings.

Verify the fix under normal conditions

Repeat the original request, a service restart and a representative workload. Confirm that readiness prevents requests from reaching an unavailable application during startup.

For a local AI deployment, also distinguish proxy failure from a model that is still loading. Keep the proxy-to-app health check separate from the model's ability to finish a generation request.

Related troubleshooting

• Docker Cannot Reach an API on Your Laptop
• Docker depends_on: Database Not Ready

This guide draws on the linked documentation. Examples are illustrative unless explicitly identified as measured results.