🚨 Docker Error Guide: 'network has active endpoints' — Cannot Remove a Network In Use

Overview

Docker refuses to delete a network while any container is still attached to it. Each attachment is an endpoint; if endpoints remain, docker network rm fails to protect the connected containers:

Error response from daemon: error while removing network: network myapp_backend id 7f3c9a2b1d4e 
has active endpoints

You will hit it on docker network rm, docker network prune, and sometimes docker compose down when a container outside the project is still connected to the project network.

Symptoms

• docker network rm myapp_backend fails while at least one container is connected.
• docker compose down leaves a network behind because a manually connected container still uses it.
• The network shows endpoints in docker network inspect even though the “main” containers are gone.
• A stale endpoint remains after an unclean container removal.

Common Root Causes

• A running container is still attached — the obvious case; disconnect or stop it first.
• A container outside the Compose project joined the network — docker network connect attached an external container, so Compose cannot remove it.
• A stopped-but-not-removed container still owns an endpoint.
• A stale/orphaned endpoint left by an unclean removal or daemon crash keeps the network “in use” with no live container.
• Force-removed containers whose endpoint cleanup did not complete.

Diagnostic Workflow

Inspect the network to list every attached container and endpoint:

docker network inspect myapp_backend

Extract just the connected container names:

docker network inspect -f '{{range .Containers}}{{.Name}} {{end}}' myapp_backend

Find containers (including stopped) attached to the network:

docker ps -a --filter network=myapp_backend

Disconnect a specific container, forcing it if it is a stale endpoint:

docker network disconnect myapp_backend <container>
docker network disconnect -f myapp_backend <container>   # for stale endpoints

If nothing is really attached, a daemon restart clears orphaned endpoints:

journalctl -u docker --since '15 min ago' | grep -i endpoint
sudo systemctl restart docker

Example Root Cause Analysis

A docker compose down on the myapp stack succeeded, but a follow-up docker network rm myapp_backend in a cleanup script failed with network myapp_backend has active endpoints. Inspecting the network revealed one attached container:

$ docker network inspect -f '{{range .Containers}}{{.Name}} {{end}}' myapp_backend
debug-shell

An engineer had earlier run docker network connect myapp_backend debug-shell to troubleshoot, attaching a container outside the Compose project. Compose only removes containers it manages, so the external debug-shell kept the network alive. Disconnecting it allowed the removal:

docker network disconnect myapp_backend debug-shell
docker network rm myapp_backend

The endpoint was live, not stale, so a plain disconnect sufficed. Where inspection shows an endpoint with no corresponding container, docker network disconnect -f or a daemon restart clears the orphan.

Prevention Best Practices

• Stop and remove all containers on a network before removing it: docker compose down handles project-managed containers automatically.
• Track manually attached containers (docker network connect) and disconnect them before teardown.
• Use docker compose down --remove-orphans to sweep up containers left from renamed or removed services.
• After an unclean daemon shutdown, restart Docker to clear orphaned endpoints before scripting network removals.
• In automation, disconnect known external containers first, then remove the network, and treat a persistent failure as a stale-endpoint case to force-clear.

Quick Command Reference

docker network inspect <net>                                  # list endpoints
docker network inspect -f '{{range .Containers}}{{.Name}} {{end}}' <net>
docker ps -a --filter network=<net>                           # attached containers
docker network disconnect <net> <container>                   # detach
docker network disconnect -f <net> <container>                # force-clear stale
docker network rm <net>                                       # remove once empty

Conclusion

network has active endpoints is Docker protecting a network that still has containers attached. List the endpoints with docker network inspect, disconnect or remove each attached container — including any external ones you connected manually — then delete the network. For genuine orphans with no live container, force-disconnect or restart the daemon. Clean teardowns with docker compose down --remove-orphans prevent it. More networking fixes are in the Docker guides.