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:8080 only. It works from the backend server itself and from nowhere else. ss -ltnp | grep 8080 on 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-IP and tell the app to trust them only from the gateway's address (trusted_proxies in Nextcloud, set_real_ip_from in 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.

Check connection in the proxy host form

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.