Nginx Proxy Manager 502 Bad Gateway: Diagnose the Upstream

Record the exact 502 and where it appears

Record whether the 502 appears on the proxied public hostname, in the NPM admin UI itself, or both, with the full response text. A 502 only on proxied traffic keeps this page applicable; a 502 on the admin UI or a renewal error belongs elsewhere. Do not proceed on a remembered paraphrase.[1]

Contact the upstream and note where you tested from

Request the upstream application directly at its own address and port, then repeat the check from a network context equivalent to NPM where possible. A result seen only from a browser or another machine is comparative evidence, because it does not repeat the NPM container path. Use only a normal non-destructive request the application already serves.[4]

Read the proxy host error log

For NPM 2.15.1, the proxy-host template writes /data/logs/proxy-host-<id>_error.log inside the NPM container. Find the storage mounted at /data in your deployment configuration; the guide's ./data:/data example puts these files under ./data/logs on the host. Use your actual mount, not a guessed working directory.[7][1]

Inspect the matching file with your existing read-only file viewer. Match the proxy hostname and request timestamp; do not assume that host ID 1 is yours. Preserve the error wording and upstream endpoint, but redact client addresses, query tokens and private names before sharing. An empty or unrelated log is inconclusive.[7]

Do not change the proxy host, upstream, or TLS settings before classification

Do not edit the forward hostname, port, or scheme, restart the upstream, or change TLS settings before comparing reachability from the NPM network context and confirming the exact log signature. A change made before classification can hide which upstream boundary actually failed.[2]

1. Compare reachability from the NPM network context

Repeat an authorized, non-destructive request from inside the NPM container using tools already present there. Keep the upstream scheme, address, port and test path identical. If no suitable client exists, record that limitation instead of treating a host-side test as equivalent. Tests on the Docker host or on the upstream are separate comparisons; neither automatically shares the NPM container network namespace.[8][9]

Record one row per execution location: target, time, response or exact error. An answer from the upstream itself combined with a failure inside NPM narrows the next checks to the NPM-to-upstream path. A failed connection does not by itself distinguish a stopped service, wrong endpoint or rejecting network rule.[3][2]

2. Classify what the forward address means from inside the NPM container

Read the recorded forward hostname or IP and forward port from the NPM container's network context. In the scoped bridge deployment, 127.0.0.1 is its own loopback. Automatic Docker service-name resolution requires a shared user-defined network. A literal LAN IP needs no hostname lookup; a hostname must resolve through the container's configured name-resolution path. The official NPM example uses a shared network and the upstream service name with its container port.[2][8]

3. Match the proxy error log signature

Connection refused: record the exact address and port and compare them with the intended listener. Treat refusal as an observation; it does not uniquely identify a stopped application. Confirm the endpoint and listener before selecting that fix.[3]

Name lookup: the reported fragment "host not found in upstream" identifies a name-resolution failure during nginx configuration loading. Issue #633 is a user report, not proof that every unresolved name produces the same startup failure. Check which name and timestamp apply to your installation.[5]

TLS: issue #3961 reports "SSL_do_handshake() failed" with "tlsv1 alert protocol version". That specific alert directs investigation toward protocol negotiation. A generic handshake failure has other possibilities, so keep its full error text instead of immediately toggling HTTP/HTTPS. These are source-reported fragments, not HomeLabFix test logs.[4][3]

4. For a refused connection, separate a stopped listener from a wrong port

Confirm whether anything listens on the recorded target from a vantage point that shares the NPM container's network view. Nothing listening means the upstream is stopped or bound elsewhere; a listener on a different port means the recorded forward port is wrong. Do not infer from host-side listening alone when NPM runs containerized.[4][2]

Stopped upstream: restore the application listener on its documented target

Start or repair the upstream application so it listens on the address and port the proxy host already records, then verify it answers directly before retesting through NPM. This branch changes the upstream, not the proxy record.[4]

Wrong port: correct the forward port to the serving port

Edit the proxy host record so the forward port matches the port the application actually serves, distinguishing internal container ports from published host ports. Retest through the proxy hostname after the correction.[2][4]

Namespace mismatch: address the upstream the way the NPM container sees it

Replace a localhost forward address with an address reachable from inside the NPM container: the Docker host address where appropriate, or the container service name after joining NPM and the upstream to a shared Docker network, using the internal container port. The official advanced configuration demonstrates exactly this service-name pattern for upstream services on the same Docker host.[2][6]

Unresolvable name: give the proxy a name it can resolve

Point the proxy host at a name that resolves from the NPM host: join NPM and a containerized upstream to a shared Docker network and use the service name, or use a DNS-resolvable fully qualified name or IP. The official advanced configuration documents the shared-network service-name pattern; in one reported case, nginx failed when a recorded container hostname vanished.[2][5]

TLS or scheme mismatch: align the recorded scheme with the upstream

Set the proxy-host scheme to the protocol the upstream actually serves. If the log names a TLS handshake failure, resolve that specific negotiation problem instead of toggling the scheme blindly. A protocol-version alert, for example, points to TLS-version negotiation between NPM and the upstream and may require upstream-side or advanced-configuration work.[4][3]

If no documented branch matches: preserve the evidence

Record the exact proxy response, the NPM version, the proxy forward hostname, port, and scheme, the reachability result from each vantage point tested (client, Docker host, NPM-equivalent network context, upstream listener), and the full proxy error log lines. Where an otherwise answering upstream stays unreachable from the NPM network context alone, keep the Docker network attachment and any routing or firewall boundary between NPM and the upstream inside the investigation scope. Send the sanitized evidence to the operator; the documented branches above cover the reported upstream patterns, not every possible backend failure.[1][4]