A very common setup, at home and at work: one small server faces the internet and runs the reverse
proxy in Docker. The actual services live on other machines in the private network.
Internet ──► :80/:443 gateway server (reverse proxy in Docker) ──► 10.0.0.21:8080 wiki ──► 10.0.0.22:3000 app ──► nas.corp.example:5001 NAS You add a host, point it at app01:8080, save, open the site and get 502 Bad Gateway. From your
laptop the service works. From the gateway server itself, curl http://app01:8080 works too.
Here are the four causes I have run into most often, why they happen, and how to check each one in a
minute. They apply to nginx, Nginx Proxy Manager, OpenResty-based proxies and most other proxies
that run in a container.
1. Short names and search domains
ping app01 works on the server because /etc/resolv.conf has a search domain:
nameserver 10.0.0.2 search corp.example The C library quietly tries app01.corp.example for you. nginx's runtime resolver does not.
When nginx resolves upstream names at request time (resolver directive with a variable in
proxy_pass, or server ... resolve in an upstream block), it sends exactly app01 to the DNS
server. Most company and router DNS servers have no answer for a single-label name, so the request
fails with something like:
[error] ... app01 could not be resolved (3: Host not found) [error] ... no live upstreams while connecting to upstream Inside Docker it is the same: Docker's embedded DNS (127.0.0.11) forwards the name as it is.
Check:
# from inside the proxy container, without the search list docker exec -it proxy nslookup app01. # trailing dot = no search domains docker exec -it proxy nslookup app01.corp.example. Fix: use the full name (app01.corp.example) or the IP address as the upstream.
2. Names that only exist in the server's /etc/hosts
Some setups have no internal DNS at all; the gateway server has a few lines in /etc/hosts:
10.0.0.21 app01.corp.example A container has its own /etc/hosts, so the name is unknown inside it. And even inside the
container, nginx's runtime resolver only talks DNS; it never reads /etc/hosts.
Fix: give the container the entry with extra_hosts, and make sure your proxy resolves such
names at startup (static proxy_pass without variables) or replaces them with their address:
services: proxy: extra_hosts: - 'app01.corp.example:10.0.0.21' 3. A Docker network that overlaps your private network
Docker picks private ranges for its networks by itself: 172.17.0.0/16 to 172.31.0.0/16, then
pieces of 192.168.0.0/16. Every docker compose up of a new project can create another one.
If your office or home network also uses, say, 172.18.0.0/16 or 192.168.16.0/20, the host gets a
route that sends that range into the Docker bridge instead of to your LAN. The symptom is very
specific: only the hosts whose backend is in that range return 502; everything else works.
Check:
docker network inspect $(docker network ls -q) --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' ip route # on the gateway server: which interface owns 10.x / 172.x / 192.168.x? Fix: give the proxy's network a range you do not use, and keep Docker away from your ranges for
all future networks:
networks: default: ipam: config: - subnet: 172.30.0.0/24 In /etc/docker/daemon.json (then restart Docker):
{ "default-address-pools": [ { "base": "172.30.0.0/16", "size": 24 } ] } 4. The backend only listens on localhost, or its firewall says no
Two classics on the backend side:
- The service listens on
127.0.0.1:8080only. It works from the backend server itself and from nowhere else.ss -ltnp | grep 8080on the backend shows the bind address. - The backend's firewall allows "the admin's PC" or a VPN range, but not the gateway server. With a bridged container, connections arrive from the gateway server's LAN address (Docker masquerades them), so that is the address to allow.
Check from the gateway's point of view, not your laptop's:
docker exec -it proxy sh -c 'nc -vz -w 5 10.0.0.21 8080' Connection refused means the address answered but nothing listens on that port (wrong port,
service down, bound to 127.0.0.1). A timeout usually means a firewall silently dropping packets, or
a route going somewhere else (see #3).
Two more things once it works
- HTTPS backends with self-signed certificates (NAS admin pages, Proxmox): nginx does not verify upstream certificates by default, so
https://upstreams just work. If the backend routes by name, also send SNI (proxy_ssl_server_name on;). - Real client IPs: the backend now sees every request coming from the gateway. Pass
X-Forwarded-For/X-Real-IPand tell the app to trust them only from the gateway's address (trusted_proxiesin Nextcloud,set_real_ip_fromin nginx). Then firewall the backend ports so only the gateway can reach them; otherwise anyone on the LAN can skip the proxy and its protections.
A one-minute checklist
| Symptom | Likely cause | First check |
|---|---|---|
could not be resolved, no live upstreams | short name / /etc/hosts only | nslookup name. inside the container |
| only hosts in one range fail | Docker subnet overlaps the LAN | docker network inspect, ip route |
Connection refused | wrong port, service down, bound to 127.0.0.1 | ss -ltnp on the backend |
| timeout after a few seconds | firewall drops, or wrong route | nc -vz from inside the container |
Why I wrote this
I maintain Corvus, an open-source (Apache-2.0)
self-hosted gateway: an NPM-style reverse proxy with WAF rules, automatic bans, bot challenges and a
waiting room, in one container. Users who run it on a separate gateway server kept hitting exactly
these four problems, and the only clue was a line in the error log.
So version 1.5.0 has a Check connection button in the host form: it resolves the target with the
gateway's own resolver (no search domains, same extra_hosts mapping), opens a TCP connection,
does a TLS handshake for https, and tells you which of the cases above you hit before you save. If
visitors still get a 502 later, the host list shows the upstream error with its reason.
Even if you never use Corvus, I hope the checklist saves you an evening. If you have hit another
cause of "502 but the backend is fine", I'd love to hear it in the comments.
