ConfigClarity › Glossary › Dangling Route

Dangling Route

A dangling route is a reverse proxy configuration entry pointing to a backend service that no longer exists — a stopped container, a removed service, or a hostname that no longer resolves — causing 502 or 504 errors.
NginxReverse ProxyTraefik502RoutingDocker

Dangling routes accumulate over time as services are added, renamed, or removed without updating the reverse proxy configuration. Nginx does not validate that upstream servers exist at startup — it will start successfully even if every defined upstream is unreachable.

In Traefik with Docker labels, dangling routes occur when a container is removed but the Nginx config referencing it was not updated. In static Nginx configurations, they occur when services are moved to different ports or hostnames without updating the proxy_pass directive.

Impact

End users see 502 (bad gateway) or 504 (gateway timeout) errors. The reverse proxy server logs are flooded with upstream connection failures. Health check monitors flag the service as down. In some configurations, Traefik will continue attempting connections to removed backends, consuming resources.

Detection

ConfigClarity's Reverse Proxy Mapper analyses your nginx.conf or Docker Compose labels, extracts all defined upstream targets, and flags any that don't correspond to a running service definition in the same config file.

Related Tools

Reverse Proxy Mapper →

Fix Guides

Nginx 502 fixUpstream timeout fix

Frequently Asked Questions

How do dangling routes happen in Docker Compose?
When a container is removed from docker-compose.yml but the Nginx config in another service still references it via proxy_pass http://removed-service:port. Docker removes the DNS entry for the removed service, but Nginx's config is not automatically updated.
Will Nginx start with a dangling upstream?
Yes. Nginx validates config syntax with nginx -t but does not check whether upstream servers are reachable at startup. The error only appears at runtime when a request is made to the dangling route.
How do I find dangling routes in my Nginx config?
Paste your nginx.conf into ConfigClarity's Reverse Proxy Mapper. It extracts all proxy_pass targets and cross-references them against the upstream definitions and Docker service names defined in the same config.

Related Fix Guides