Nginx Proxy Manager 502 Bad Gateway: 4 Docker Causes

24 min readBy Yun Sanghun (M. Yun)

I ran Nginx Proxy Manager (jc21/nginx-proxy-manager:2.11.3, OpenResty 1.25.3.2) with Docker Compose on my Windows 11 PC (Docker Desktop, Docker Engine 27.5.1), placed a lightweight traefik/whoami backend behind it on a shared bridge network, and then broke the stack systematically. Below is the exact Compose configuration I used, how first-run administrator creation works across current and legacy releases, all four ways I reproduced a 502 Bad Gateway with the verbatim /data/logs/proxy-host-1_error.log line for each, why the green Online status indicator stays lit during an outage, and both ways port 81 stops answering.

Nginx Proxy Manager Port 81 Boot Race & Custom Bridge (npm_default) Matrix

NPM Failure PlanePort 81 / Proxy SymptomNPM-Specific Root Cause (SQLite / MariaDB / Bridge)Verified Docker Compose Fix
Port 81 Boot Race (SQLite vs MariaDB)Port 81 refuses login or returns Bad Gateway for 5 to 25sNode.js API (port 3000) waits on Knex schema init in /data/database.sqlite or jc21/mariadb-aria InnoDB startupWait for Listening on port 3000 ... in docker logs; add MariaDB service_healthy check
Port 81 First Login (v2.13+ vs v2.11.3)admin@example.com / changeme rejected on fresh stackNPM 2.13.0+ removed seeded credentials and serves setup wizard when /api/ reports "setup":falseCreate owner account in port 81 Welcome wizard (or inspect INITIAL_ADMIN_* env vars)
Split Compose Stack (npm_default)502 Bad Gateway after 4.02 s while NPM dot stays green OnlineApp started in a separate docker-compose.yml sits outside NPM's custom bridge; OpenResty DNS 127.0.0.11 returns Server failureAttach both stacks to an external bridge (npm_default or gfl-npm-net) and forward by service name
NPM Forward Host / Port Trap502 Bad Gateway in 0.02 s (errno 111: Connection refused)Proxy Host dialog set to 127.0.0.1 or published host port (e.g. 8080) instead of container port (80)Set Forward Hostname/IP to Compose service name and Forward Port to internal container port; check /data/logs/proxy-host-1_error.log

Need custom proxy_read_timeout or client_max_body_size directives for Nginx Proxy Manager's Advanced tab, or converting docker run backends onto npm_default? Use our Nginx 502/504 Timeout Config Generator and Docker Run to Compose Converter.

TL;DR & 502 Bad Gateway Diagnostic Router

  • First login & setup wizard: On current releases (2.13.0+), there is no default admin@example.com / changeme login; visiting port 81 opens the "Welcome! Get started by creating your admin account" setup wizard when /api/ reports "setup":false. On 2.11.3 / 2.12.x images that still seed those defaults, rotate both the email and password immediately via the user menu.
  • Four reproduced 502 Bad Gateway causes: A stopped backend container and a backend on a different Docker network both failed after ~4.02 s and logged could not be resolved (2: Server failure). A wrong forward port (8080 instead of 80) and using 127.0.0.1 as the forward host both failed in 0.02 s and logged connect() failed (111: Connection refused).
  • The status dot trap: The Proxy Hosts table continues to display a green Online badge (nginx_online: true) while client requests receive 502 Bad Gateway. Always check /data/logs/proxy-host-<ID>_error.log instead of the UI dot.
  • Port 81 failures: Omitting 81:81 from ports: caused host requests to fail with curl: (7) Failed to connect to 127.0.0.1 port 81 after 2040 ms even though port 81 answered 200 inside the container. When another container already held 127.0.0.1:81, Compose aborted with Bind for 127.0.0.1:81 failed: port is already allocated.
  • Mandatory volumes: Keep both /data and /etc/letsencrypt mounted. Omitting /etc/letsencrypt stops container initialization immediately with ERROR: /etc/letsencrypt is not mounted! Check your docker configuration. (exit code 1).
Symptom / HTTP ResultMeasured LatencyExact Log / CLI SignatureRoot CauseVerified Fix
502 Bad Gateway4.03 swhoami could not be resolved (2: Server failure)Backend container is stopped (Exited)docker start gfl-npm-whoami (200 OK in 0.02 s)
502 Bad Gateway0.02 sconnect() failed (111: Connection refused) ... upstream: "http://172.18.0.2:8080/"Wrong Forward Port (8080 vs container port 80)Set Forward Port to internal container port 80
502 Bad Gateway4.02 sgfl-npm-whoami2 could not be resolved (2: Server failure)Backend is on an isolated Docker networkdocker network connect gfl-npm-other gfl-npm-app or shared external network
502 Bad Gateway0.02 sconnect() failed (111: Connection refused) ... upstream: "http://127.0.0.1:8081/"Forward Host set to 127.0.0.1 (loops back inside NPM)Use Compose service name whoami:80 or host.docker.internal:8081
curl: (7) on :812.04 sFailed to connect to 127.0.0.1 port 81 after 2040 ms81:81 mapping missing under ports:Restore '127.0.0.1:81:81' and run docker compose up -d
Compose fails (exit 1)ImmediateBind for 127.0.0.1:81 failed: port is already allocatedAnother container/process holds 127.0.0.1:81Remap host side to '127.0.0.1:8181:81' or stop the conflicting container

What I Ran (Lab Environment Baseline)

Stack LayerTested Lab Configuration
Nginx Proxy Managerjc21/nginx-proxy-manager:2.11.3 (OpenResty 1.25.3.2, Node.js internal API on port 3000, SQLite /data/database.sqlite)
Docker RuntimeDocker Desktop on Windows 11, Docker Engine 27.5.1, user-defined bridge network gfl-npm-net (172.18.0.0/16)
Upstream Backendtraefik/whoami:latest (gfl-npm-whoami), a tiny Go HTTP server that echoes received request headers and container IP
Port BindingsAll host ports bound strictly to loopback (127.0.0.1:80:80, 127.0.0.1:81:81, 127.0.0.1:443:443). No public domain or router port forwarding
Automation & VerificationHeadless Playwright browser session on port 81 paired with direct REST calls to http://127.0.0.1:81/api/ and curl probes

From a cold start with the image already pulled (docker compose pull took 28.4 s; the uncompressed image is 1.91 GB on disk), docker compose up -d returned after 0.7 s. Port 81 answered HTTP 200 after 1.7 s, and GET /api/ responded at 2.8 s with {"status":"OK","setup":false,"version":{"major":2,"minor":11,"revision":3}}. Adding the opt-in /usr/bin/check-health probe moved the container state from starting at +5 s to healthy at +10 s:

Nginx Proxy Manager 2.11.3 first start timings, opt-in /usr/bin/check-health status, /etc/letsencrypt not mounted error, and INITIAL_ADMIN_PASSWORD plaintext log audit
First-start telemetry on jc21/nginx-proxy-manager:2.11.3: port 81 responds in 1.7 s, /usr/bin/check-health reaches healthy at +10 s, and omitting /etc/letsencrypt aborts container boot with exit code 1.

Looking closely at the four diagnostic blocks in the first-start log above highlights three operational behaviors that catch administrators off guard during initial deployment. First, about five seconds after boot, steady-state memory usage settled at 113.8 MiB for gfl-npm-app and 3.14 MiB for gfl-npm-whoami, while Docker Compose created only the two named volumes (gfl-npm-data mounted at /data and gfl-npm-letsencrypt mounted at /etc/letsencrypt). Inside /data, the initialization scripts populated database.sqlite, keys.json, logs/, and nginx/, whereas /etc/letsencrypt remained empty because no Let's Encrypt certificate was requested.

Sequence diagram comparing Nginx Proxy Manager port 81 cold-boot readiness and 127.0.0.1 loopback 502 failures against /usr/bin/check-health startup gating and shared npm_default Docker bridge DNS routing
Readiness & Bridge Sequence: Waiting for /usr/bin/check-health (healthy at +10 s) prevents premature port 81 login errors, while attaching backend apps to the shared Docker Compose bridge eliminates 127.0.0.1 loopback 502 Bad Gateway traps.

Second, the third block in that capture comes from a separate test container launched with only a /data volume and no /etc/letsencrypt mount. Instead of creating an ephemeral directory inside the container root filesystem, the s6-rc prepare service explicitly checks whether /etc/letsencrypt is a mountpoint and aborts immediately with ERROR: /etc/letsencrypt is not mounted! Check your docker configuration. and s6-rc: warning: unable to start service prepare: command exited 1. Even in a local HTTP-only lab, you must mount both volumes.

First Login on Port 81: Setup Wizard vs Legacy Default Credentials

Many older tutorials still instruct you to sign in on port 81 using admin@example.com and changeme. That was governed by backend/setup.js in versions up through 2.12.x when no environment variables were supplied. Starting in 2.13.0, the release notes replaced that seed step with an interactive first-run Setup Wizard whenever GET /api/ returns "setup":false:

Nginx Proxy Manager first visit on http://127.0.0.1:81 showing the Welcome create your admin account setup wizard card
First visit to http://127.0.0.1:81: creating the administrator account via the setup wizard or replacing the initial bootstrap credentials immediately invalidates default login vectors.

When I opened http://127.0.0.1:81 in a fresh browser session against an uninitialized database, Nginx Proxy Manager rendered the Welcome! Get started by creating your admin account setup card rather than a login prompt. The wizard requires three fields, Full Name, Email address, and New Password (minimum 8 characters), and submitting the form sends a POST /api/users bootstrap request that creates administrator user ID 1, flips setup to true, and signs you straight into the dashboard.

To verify how Nginx Proxy Manager wires the Admin WebUI, the internal Node.js API, and the SQLite credential store together inside the container, I inspected the live process tree, listening TCP sockets (ss -tulpn), host port mappings (docker port gfl-npm-app), and the user and auth tables inside /data/database.sqlite right after account creation:

Terminal audit of gfl-npm-app showing ss -tulpn OpenResty sockets on ports 80, 81, and 443, Node.js on 127.0.0.1:3000, docker port bindings, and SQLite bcrypt password hash
Internal socket table inside gfl-npm-app: OpenResty fronts port 81 and proxies /api requests to the internal Node.js backend on port 3000 while persisting bcrypt hashes in /data/database.sqlite.

The socket and database inspection inside gfl-npm-app explains how port 81 actually works under the hood. A single nginx: master process (OpenResty 1.25.3.2, PID 246) listens on 0.0.0.0:80, 0.0.0.0:81, and 0.0.0.0:443 inside the container network namespace, while the backend Node.js application (node --abort_on_uncaught_exception --max_old_space_size=250 index.js, PID 261) listens exclusively on container loopback 127.0.0.1:3000. When your browser requests http://127.0.0.1:81/, OpenResty serves the static frontend bundle and proxies every /api/* call to http://127.0.0.1:3000.

Meanwhile, querying /data/database.sqlite (92.0 KB alongside the 2.2 KB RSA keypair file /data/keys.json) confirms that Nginx Proxy Manager stores the account record in the user table (id=1, email='admin@example.test', roles='["admin"]') and stores the password separately in the auth table with type='password' and a cost-13 bcrypt hash ($2b$13$WKga5gYCTg67KuBlshbOPO...). If you are running a 2.11.3 or 2.12.x container where the legacy admin@example.com / changeme account was seeded automatically, open the top-right user menu immediately, click Edit Profile to replace the default email, and click Change Password to rotate the secret:

Nginx Proxy Manager Change Password modal with Current Password, New Password, and Confirm Password fields paired with POST /api/tokens verification
Rotating the administrator secret through User Menu -> Change Password updates the bcrypt hash in /data/database.sqlite and immediately rejects the old credential with HTTP 400.

Submitting the Change Password dialog sends PUT /api/users/1/auth with your current and new passwords, re-computing the $2b$13$ bcrypt hash in /data/database.sqlite. I verified the rotation immediately against POST /api/tokens: attempting to authenticate with the old password returned HTTP 400 Bad Request ({"error":{"message":"Invalid email or password"}}), whereas authenticating with the new password returned HTTP 200 OK and a fresh RS256 bearer token. If you ever get locked out of an existing instance because the password in auth.secret is lost, see our companion guide on resetting the Nginx Proxy Manager password in SQLite.

Setup: The Production-Hardened Docker Compose File

My lab stack starts from the official minimal configuration in the Nginx Proxy Manager Quick Setup guide, with five deliberate engineering improvements: every published port is bound explicitly to 127.0.0.1 so Docker does not expose port 81 on all interfaces; named volumes (gfl-npm-data and gfl-npm-letsencrypt) replace relative bind mounts; the project, containers, and bridge network use deterministic gfl- names; the opt-in /usr/bin/check-health healthcheck is included directly; and the whoami backend sits on the shared gfl-npm-net bridge without publishing any host ports of its own:

# File: docker-compose.yml
# Hardened Nginx Proxy Manager 2.11.3 + traefik/whoami lab stack on shared gfl-npm-net bridge
name: gfl-npm
services:
  app:
    image: 'jc21/nginx-proxy-manager:2.11.3'
    container_name: gfl-npm-app
    restart: unless-stopped
    ports:
      - '127.0.0.1:80:80'    # Public HTTP (bound to loopback for local test)
      - '127.0.0.1:81:81'    # Admin WebUI (keep on 127.0.0.1; tunnel via SSH on VPS)
      - '127.0.0.1:443:443'  # Public HTTPS
    volumes:
      - gfl-npm-data:/data
      - gfl-npm-letsencrypt:/etc/letsencrypt
    healthcheck:
      test: ["CMD", "/usr/bin/check-health"]
      interval: 10s
      timeout: 3s
    networks:
      - gfl-npm-net

  whoami:
    image: 'traefik/whoami:latest'
    container_name: gfl-npm-whoami
    networks:
      - gfl-npm-net

networks:
  gfl-npm-net:
    name: gfl-npm-net

volumes:
  gfl-npm-data:
    name: gfl-npm-data
  gfl-npm-letsencrypt:
    name: gfl-npm-letsencrypt
Code editor showing complete docker-compose.yml for gfl-npm with loopback port bindings, /data and /etc/letsencrypt volumes, check-health, and shared gfl-npm-net network
Complete docker-compose.yml for gfl-npm: binding ports to 127.0.0.1, mounting both /data and /etc/letsencrypt named volumes, and attaching app and whoami to gfl-npm-net.

If you prefer to keep the base docker-compose.yml minimal and layer the healthcheck only in environments that monitor container health status, you can split the healthcheck: block into a separate override file (docker-compose.healthcheck.yml) as documented in the NPM Advanced Configuration docs:

# File: docker-compose.healthcheck.yml
services:
  app:
    healthcheck:
      test: ["CMD", "/usr/bin/check-health"]
      interval: 10s
      timeout: 3s

Before creating our first proxy host, it is worth contrasting this hardened stack against two common shortcuts people try in docker-compose.yml: dropping the /etc/letsencrypt volume when testing plain HTTP locally, and setting INITIAL_ADMIN_EMAIL plus INITIAL_ADMIN_PASSWORD in environment variables to skip the first-run login step. I tested both in isolated throwaway containers:

Split terminal comparison of missing /etc/letsencrypt mount exit code 1 and INITIAL_ADMIN_PASSWORD plaintext log leak versus hardened dual-volume boot
Boot comparison: omitting /etc/letsencrypt triggers an immediate exit code 1, while INITIAL_ADMIN_PASSWORD writes the plaintext secret twice: once to stdout and once to /data/logs/.

As the side-by-side comparison demonstrates, both shortcuts introduce immediate problems. Omitting /etc/letsencrypt causes s6-rc to halt container initialization before OpenResty or Node.js can even start (ERROR: /etc/letsencrypt is not mounted! Check your docker configuration.). Worse, when you pass INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD via environment variables (documented under Auto Initial User Creation), the setup script echoes the raw password in plain text twice: once to container stdout (visible to anyone who can run docker logs) and once to disk inside /data/logs/ on the line Creating a new user: <email> with password: <plaintext>. Creating or rotating the account through the WebUI over 127.0.0.1:81 leaves zero plaintext passwords in your logs.

Creating a First Proxy Host & Verifying HTTP 200 Routing

With both gfl-npm-app and gfl-npm-whoami running on gfl-npm-net, I created Proxy Host #1 to route requests for whoami.localhost to the whoami container on port 80 and tested it from the host terminal with curl (for a side-by-side footprint comparison against Traefik and Caddy on the same backend, see our Traefik vs Caddy vs Nginx Proxy Manager Docker RAM benchmark; on managed WordPress stacks where Varnish sits ahead of Apache, compare our Cloudways 502 vs Varnish 503 diagnostic; and when reaching a native Windows listener from Docker Desktop, see fixing Docker ECONNREFUSED 127.0.0.1 on Windows 11):

Terminal verification of curl -i -H Host: whoami.localhost http://127.0.0.1/ returning HTTP 200 OK from OpenResty and traefik/whoami on 172.18.0.2
Sending GET / with Host: whoami.localhost to 127.0.0.1:80 routes through OpenResty to http://whoami:80 on gfl-npm-net and returns HTTP 200 OK in 30 ms.

Sending curl -i -H "Host: whoami.localhost" http://127.0.0.1/ returned HTTP/1.1 200 OK in 0.030 s (30 ms) with response headers Server: openresty and X-Served-By: whoami.localhost. The upstream traefik/whoami payload confirmed that container 6963d4bca755 received the request on its internal gfl-npm-net bridge IP 172.18.0.2 from NPM's bridge IP 172.18.0.3:48356, while OpenResty populated X-Forwarded-For: 172.18.0.1, X-Forwarded-Proto: http, X-Forwarded-Scheme: http, and X-Real-Ip: 172.18.0.1. At the same instant, /data/logs/proxy-host-1_access.log recorded [200 200] - GET http whoami.localhost "/" [Client 172.18.0.1] [Length 290] [Gzip -] [Sent-to whoami].

In the Admin UI under Hosts → Proxy Hosts → Add Proxy Host, achieving that clean route requires filling in exactly four fields on the Details tab while leaving the SSL tab set to None for local loopback testing:

Nginx Proxy Manager Add Proxy Host modal showing Details tab (whoami.localhost -> http://whoami:80) and SSL tab (SSL Certificate: None)
Add Proxy Host configuration: setting Forward Hostname to the Docker Compose service name (whoami) and Forward Port to the internal container port (80) with SSL set to None for local testing.

Here is why each of those four fields in the Add Proxy Host modal matters when proxying to another Docker container:

  • Step 1: Domain Names (whoami.localhost): Sets the server_name directive inside OpenResty. Any HTTP request arriving on port 80 whose Host: header matches whoami.localhost is routed to this virtual host.
  • Step 2: Scheme (http): Specifies the protocol OpenResty uses between NPM and the backend container over the internal Docker bridge, not the external client protocol. Because traefik/whoami listens for plain HTTP internally, this must be http even if you later enable HTTPS on the public side.
  • Step 3: Forward Hostname / IP (whoami): Must be the Docker Compose service name (whoami) or container name (gfl-npm-whoami) on the shared gfl-npm-net bridge, never 127.0.0.1 or localhost.
  • Step 4: Forward Port (80): Must be the port the process listens on inside the backend container (80), not a host-mapped port.

To see how Nginx Proxy Manager translates that modal into actual Nginx directives, and why saving a proxy host succeeds even when the upstream host is offline, I inspected the generated virtual host file /data/nginx/proxy_host/1.conf and the included resolver configuration inside gfl-npm-app:

Generated /data/nginx/proxy_host/1.conf and /etc/nginx/conf.d/include/resolvers.conf showing dynamic $server variable and Docker DNS 127.0.0.11 resolver
Inside /data/nginx/proxy_host/1.conf: NPM stores the forward host in a variable ($server) and uses Docker's 127.0.0.11 DNS resolver with a 10 s TTL, deferring hostname lookup until a request arrives.

Inspecting /data/nginx/proxy_host/1.conf reveals three architectural details that explain every 502 Bad Gateway behavior we are about to see. First, instead of emitting a static upstream block, NPM writes three Nginx variables at the top of the server block: set $forward_scheme http;, set $server "whoami";, and set $port 80;, which are then passed to proxy_pass $forward_scheme://$server:$port$request_uri; inside /etc/nginx/conf.d/include/proxy.conf. Because $server is a runtime variable rather than a static hostname literal, OpenResty does not resolve whoami during nginx -t or config reload; instead, it queries Docker's embedded DNS server (resolver 127.0.0.11 valid=10s; in /etc/nginx/conf.d/include/resolvers.conf) when an HTTP request actually arrives.

Second, notice line 14 of 1.conf: error_log /data/logs/proxy-host-1_error.log warn;. Nginx Proxy Manager isolates upstream errors into a per-host log file named after the proxy host's numeric database ID. If you only check docker logs gfl-npm-app during a 502 Bad Gateway outage, you will miss the root cause completely. Always tail the specific proxy host error log:

docker exec gfl-npm-app tail -n 20 /data/logs/proxy-host-1_error.log

502 Bad Gateway: All Four Causes Reproduced with Exact Error Logs

Starting from the working whoami.localhost proxy host (ID 1), I broke one variable at a time, sent the same GET / request with Host: whoami.localhost, measured the exact response time, and captured the new line written to /data/logs/proxy-host-1_error.log:

Nginx Proxy Manager 502 Bad Gateway reproduced across four causes with exact /data/logs/proxy-host-1_error.log lines and verified fixes
Empirical reproduction of all four 502 Bad Gateway causes in /data/logs/proxy-host-1_error.log: DNS resolution failures take ~4.02 s (2: Server failure) while wrong port and 127.0.0.1 fail in 0.02 s (111: Connection refused).

Here are the four verbatim error log lines recorded in /data/logs/proxy-host-1_error.log across the four test cases:

# Cause 1: backend container stopped (docker stop gfl-npm-whoami) -> 502 after 4.03 s
[error] 304#304: *81 whoami could not be resolved (2: Server failure), client: 172.18.0.1, server: whoami.localhost, request: "GET / HTTP/1.1", host: "whoami.localhost"

# Cause 2: wrong forward port (8080; whoami listens on 80) -> 502 in 0.02 s
[error] 381#381: *95 connect() failed (111: Connection refused) while connecting to upstream, client: 172.18.0.1, server: whoami.localhost, request: "GET / HTTP/1.1", upstream: "http://172.18.0.2:8080/", host: "whoami.localhost"

# Cause 3: backend on a Docker network NPM is not attached to -> 502 after 4.02 s
[error] 451#451: *111 gfl-npm-whoami2 could not be resolved (2: Server failure), client: 172.18.0.1, server: whoami.localhost, request: "GET / HTTP/1.1", host: "whoami.localhost"

# Cause 4: 127.0.0.1 as the forward host (published on host as 127.0.0.1:8081) -> 502 in 0.02 s
[error] 535#535: *129 connect() failed (111: Connection refused) while connecting to upstream, client: 172.18.0.1, server: whoami.localhost, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:8081/", host: "whoami.localhost"

Mapping those four error signatures onto the Docker network topology makes it immediately clear why two of them fail in 4.02–4.03 s while the other two fail in 0.02 s:

Docker Compose network and DNS topology diagram comparing 127.0.0.1 loopback trap, isolated bridge network SERVFAIL, and shared gfl-npm-net bridge routing
Packet and DNS resolution paths inside Docker Compose: why 127.0.0.1 loops back into the NPM container, why isolated networks fail at 127.0.0.11 after 4 s, and how shared bridge routing reaches 172.18.0.2:80.

As the topology diagram illustrates, the four 502 Bad Gateway causes split cleanly into two failure domains:

  1. DNS Resolution Failures (could not be resolved (2: Server failure), Causes #1 & #3): When OpenResty evaluates $server on an incoming request, it queries Docker's embedded DNS resolver at 127.0.0.11:53. When the backend container is stopped (Cause #1, docker stop gfl-npm-whoami), Docker removes its A record from gfl-npm-net; when the backend runs in a separate Compose project on its own default bridge (Cause #3, gfl-npm-whoami2 on gfl-npm-other), 127.0.0.11 refuses to resolve names across isolated networks. In both cases, OpenResty waits approximately 4.02–4.03 s before logging (2: Server failure) and returning 502.
  2. TCP Connection Refusals (connect() failed (111: Connection refused), Causes #2 & #4): When DNS succeeds (or an IP literal is used), OpenResty sends a TCP SYN packet directly to the resolved upstream socket. In Cause #2 (whoami:8080), whoami resolves to 172.18.0.2, but the container only listens on port 80, so its kernel replies with an immediate TCP RST in 0.02 s. In Cause #4 (127.0.0.1:8081), 127.0.0.1 refers to gfl-npm-app's own network namespace (not your host PC) so OpenResty probes port 8081 inside itself and gets an immediate TCP RST in 0.02 s. For plain Nginx containers outside NPM that hit the same upstream refusal, see Nginx 502 Bad Gateway in Docker: Fix Upstream Connection Refused.

Plotting the measured response latencies across all six tested upstream states side-by-side highlights this 200x timing difference between a TCP RST refusal (20 ms) and a Docker DNS SERVFAIL timeout (4,020–4,030 ms):

Matplotlib chart comparing response latency across six proxy host states (20 ms TCP RST vs 4,020 ms DNS timeout) and cold-start readiness timings
Measured response times across all six test states: DNS failures (2: Server failure) block for 4.02–4.03 s waiting on 127.0.0.11, whereas TCP RST refusals (111: Connection refused) return 502 in 20 ms.

That latency gap is a practical shortcut even before you open the logs: if clicking a proxied link returns 502 Bad Gateway instantaneously (~20 ms), you are looking at a 111: Connection refused port or loopback mismatch (Causes #2 or #4); if the browser tab spins for four seconds (~4,020 ms) before showing 502 Bad Gateway, OpenResty is timing out on Docker DNS lookup (2: Server failure, Causes #1 or #3).

Why the Green "Online" Status Dot Stays Lit During a 502 Outage

One of the most confusing parts of debugging Nginx Proxy Manager is that the Proxy Hosts table continues to display a green Online status dot while every client request returns 502 Bad Gateway. To verify why, I queried GET /api/nginx/proxy-hosts while Proxy Host #1 was pointed at broken port 8080 and simultaneously ran curl against http://whoami.localhost/:

Terminal audit showing NPM API reporting nginx_online: true while curl receives HTTP/1.1 502 Bad Gateway and live recovery via docker network connect
NPM API inspection during an active 502 outage: nginx_online remains true because OpenResty syntax validation passed when 1.conf was generated, not because the upstream port is reachable.

The API JSON payload explains the paradox: "meta": {"nginx_online": true, "nginx_err": null}. In Nginx Proxy Manager's backend code, nginx_online is a boolean flag recorded when NPM writes /data/nginx/proxy_host/1.conf and runs /usr/sbin/nginx -t followed by /usr/sbin/nginx -s reload. Because set $server "whoami"; and set $port 8080; are valid Nginx syntax, nginx -t exits with 0 and NPM marks the host as nginx_online: true. NPM never performs an active TCP or HTTP health probe against http://whoami:8080.

Notice also the bottom command in that terminal capture: in Cause #3 (where gfl-npm-whoami2 was on gfl-npm-other), running docker network connect gfl-npm-other gfl-npm-app attached the running NPM container to the backend's network and made the very next request return HTTP/1.1 200 OK in 0.030 s without even clicking Save in the NPM WebUI. Meanwhile, comparing the NPM WebUI row (ID 4416) against the client browser viewport (ID 4417) during the port 8080 test shows how deceptive the green badge looks in practice:

Nginx Proxy Manager Proxy Hosts table showing green Online status dot for http://whoami:8080 while the browser displays OpenResty 502 Bad Gateway
Visual proof of the status indicator trap: the Proxy Hosts table displays a green Online badge for http://whoami:8080 at the exact moment client requests receive OpenResty's 502 Bad Gateway page.

In the top viewport above, the Proxy Hosts table lists whoami.localhost with destination http://whoami:8080 and a green Online pill; in the bottom viewport captured at the exact same moment, the browser receives the default 154-byte OpenResty 502 Bad Gateway HTML page. My scripted tests received that exact same 502 response body in all four failure scenarios, which is why reading /data/logs/proxy-host-1_error.log is mandatory.

Connecting Separate Compose Projects & Fixing Port 81 Conflicts

While docker network connect gfl-npm-other gfl-npm-app is useful for a quick live test, an imperative attachment can be lost when containers are recreated. When your backend services live in their own docker-compose.yml directories, the official NPM best-practice guide recommends declaring the shared NPM network (gfl-npm-net) as external: true in each backend Compose project. Similarly, if another container on your machine already occupies host port 81, you can remap only the host side of NPM's admin port to 127.0.0.1:8181:81:

# 1. In a separate backend project's docker-compose.yml: attach to existing gfl-npm-net
services:
  whoami2:
    image: 'traefik/whoami:latest'
    container_name: gfl-npm-whoami2
    networks:
      - gfl-npm-net

networks:
  gfl-npm-net:
    external: true

# 2. In admin8181.override.yml: remap host port 81 -> 8181 while keeping 127.0.0.1 binding
services:
  app:
    ports: !override
      - '127.0.0.1:80:80'
      - '127.0.0.1:8181:81'
      - '127.0.0.1:443:443'
Code editor showing external: true Docker network YAML for multi-project Compose stacks and 127.0.0.1:8181:81 host port remap override
Connecting a second Compose project via an external gfl-npm-net declaration and remapping the host admin port to 127.0.0.1:8181:81 when port 81 is already allocated.

To verify how Docker Compose behaves when port 81 does not open on the host, I reproduced both safe local failure cases from the folder containing compose.yml:

  1. Case A, The 81 mapping is missing from ports:: I launched NPM with an override file (no81.override.yml) that published only ports 80 and 443. Running docker port gfl-npm-app listed only 80/tcp -> 127.0.0.1:80 and 443/tcp -> 127.0.0.1:443, and a host request failed with curl: (7) Failed to connect to 127.0.0.1 port 81 after 2040 ms: Could not connect to server. However, running curl inside the container against http://127.0.0.1:81/ still returned HTTP 200, proving that NPM itself was healthy and only the host port mapping was missing. Putting '127.0.0.1:81:81' back immediately restored host access.
  2. Case B, Another container already holds 127.0.0.1:81: I stopped gfl-npm-app and started a dummy container on port 81 (docker run -d --name gfl-npm-busy81 -p 127.0.0.1:81:80 traefik/whoami:latest). Running docker compose up -d app aborted with exit code 1 and printed Error response from daemon: ... Bind for 127.0.0.1:81 failed: port is already allocated, while requests to http://127.0.0.1:81/ returned gfl-npm-busy81's page (Hostname: 7b9b3235f86c). Applying admin8181.override.yml (127.0.0.1:8181:81) brought NPM up cleanly with HTTP 200 on http://127.0.0.1:8181/. For deeper host socket conflict resolution across Windows and Linux, see Docker Port Is Already Allocated: How to Find and Kill the Process.
Terminal log reproducing Port 81 not published (curl exit 7 after 2040 ms) and Port 81 already allocated (Bind for 127.0.0.1:81 failed) with verified fixes
Reproducing both port 81 failures: omitting 81:81 causes curl (7) on the host while port 81 still answers 200 inside the container; a conflicting container triggers Bind for 127.0.0.1:81 failed: port is already allocated.

If port 81 answers in your browser but renders another application's page instead of Nginx Proxy Manager, check docker ps (specifically the PORTS column) to see which container owns 127.0.0.1:81 or 0.0.0.0:81. While the NPM documentation also mentions an NPM_ADMIN_PORT environment variable to change the listening port inside the container, remapping the left-hand host side of the Compose port string ('127.0.0.1:8181:81') is cleaner because OpenResty and /usr/bin/check-health continue to use standard port 81 inside the container.

Combining our socket checks and /data/logs/proxy-host-<ID>_error.log signatures yields a deterministic troubleshooting decision tree you can walk through in under 60 seconds whenever port 81 or a proxy host fails:

Diagnostic decision tree flowchart for Nginx Proxy Manager branching on port 81 socket bindings and proxy-host-N_error.log error signatures
Step-by-step triage flow for Nginx Proxy Manager: branching on proxy-host-N_error.log signatures (2: Server failure vs 111: Connection refused) and docker port bindings.

Walking the decision tree from top to bottom eliminates guesswork:

  • If the admin UI on port 81 fails to load, run docker ps -a --filter "name=gfl-npm-app" and docker port gfl-npm-app first. An Exited (1) container points to a missing /etc/letsencrypt mount; a running container without 81/tcp in docker port means 81:81 was omitted from ports:; and a daemon port is already allocated error means you should either stop the conflicting container or remap the host port to 127.0.0.1:8181:81.
  • If a proxy host returns 502 Bad Gateway, ignore the green Online dot in the UI and run docker exec gfl-npm-app tail -n 20 /data/logs/proxy-host-<ID>_error.log. If the log line says could not be resolved (2: Server failure) after a ~4 s wait, start the stopped backend container or attach both containers to the same Docker network (gfl-npm-net). If the log line says connect() failed (111: Connection refused) in 0.02 s, inspect the upstream: "http://<IP>:<PORT>/" field: 127.0.0.1 means you accidentally pointed NPM at itself, whereas 172.18.0.x:<PORT> means the Forward Port does not match the backend container's internal listening port.

For quick side-by-side reference during incident triage, the consolidated troubleshooting matrix card below summarizes all six reproduced failure modes, their exact timings, UI states, log strings, and verified fixes:

Consolidated troubleshooting reference matrix summarizing all four 502 Bad Gateway causes and both port 81 failure modes with timings, log strings, and fixes
Consolidated troubleshooting matrix across all four 502 Bad Gateway root causes and both port 81 failure states with exact error log strings and recovery commands.

Limits, Scope & Pre-Production VPS Hardening Checklist

Before deploying this stack beyond a local PC, keep the exact boundaries of what I tested in mind:

  • SSL certificates were not tested (no public domain): In my local loopback lab, the SSL tab of the proxy host modal (ID 4419) remained at SSL Certificate: None with Force SSL, HTTP/2 Support, and HSTS Enabled turned off. Requesting a real Let's Encrypt certificate requires either a public domain pointed at ports 80/443 or a DNS-01 API token.
  • Single-host Docker Desktop baseline: All measurements come from single runs on Windows 11 with Docker Desktop (Engine 27.5.1). Notably, host.docker.internal:8081 worked as a fix for Cause #4 because Docker Desktop injects that hostname automatically; on Linux Docker Engine, you must either add extra_hosts: ["host.docker.internal:host-gateway"] or, better yet, use a shared Docker bridge network (gfl-npm-net) and the Compose service name.

When moving Nginx Proxy Manager onto a Linux VPS, apply the three hardening rules summarized in the scorecard below, especially binding port 81 to 127.0.0.1 so Docker does not bypass your host firewall (see Docker Bypassing UFW Firewall on Ubuntu: Check Your Port Bindings):

Pre-production and VPS hardening checklist card covering 127.0.0.1:81 loopback binding, SSH tunnel access, avoiding INITIAL_ADMIN_PASSWORD leaks, and dual volumes
Pre-production hardening scorecard for Nginx Proxy Manager: binding port 81 to 127.0.0.1, avoiding plaintext INITIAL_ADMIN_PASSWORD logs, and verifying shared Docker bridge networks.

Last reviewed: 2025-02-14. Tested on Nginx Proxy Manager 2.11.3 (OpenResty 1.25.3.2) with Docker Desktop (Docker Engine 27.5.1) on Windows 11, all ports bound to 127.0.0.1. The admin UI was driven through a headless Playwright browser session and verified against the NPM REST API. All four 502 Bad Gateway causes, both port 81 failure states, the INITIAL_ADMIN_PASSWORD plaintext log exposure, and the opt-in /usr/bin/check-health probe were reproduced and verified. SSL certificate issuance was not tested (no public domain).

Nginx Proxy Manager Port 81 Setup & Upstream 502 Q&A

Why does Nginx Proxy Manager show a green Online badge while returning 502 Bad Gateway?

The green Online status pill in Nginx Proxy Manager v2.11.3 only indicates that OpenResty parsed and loaded the generated proxy-host Nginx config syntax without error. It does not probe whether your upstream backend container is reachable.

What are the four most common causes of 502 Bad Gateway in Nginx Proxy Manager?

Pointing Forward Hostname at 127.0.0.1 instead of the container name, entering the host-mapped port instead of the internal container port, running NPM and the backend on separate Docker bridge networks, or selecting https Scheme when the backend speaks plain HTTP.

Where are the per-host upstream error logs stored inside the Nginx Proxy Manager container?

Run docker exec against your NPM container and read /data/logs/proxy-host-N_error.log. Look for no resolver defined / could not be resolved (stopped container or split Docker network) versus connect() failed 111: Connection refused (wrong port or 127.0.0.1).

100% Client-Side Utilities · Printable A4 Runbook

Run Prefilled Sizing Math & Download the 1-Page Runbook

Replace fragile GUI proxy setups with declarative Nginx, Caddy 2, or Traefik v3 configs and boot-ordered health watchdogs.

Paired Prefilled Calculators & Vector PDF Checklist

Yun Sanghun (M. Yun) · Linux, Docker & AI Infrastructure Engineer