Fix: Docker error: network has active endpoints

The Error

You try to remove a Docker network and get:

Error response from daemon: error while removing network: network my-network id abc123def456
has active endpoints

Or:

error: failed to remove network: network my-network has active endpoints

Or during docker-compose down:

ERROR: error while removing network: network my-project_default has active endpoints

Docker refuses to remove the network because one or more containers are still connected to it. Docker networks cannot be deleted while any container — running or stopped — is attached.

Why This Happens

Docker networks are reference-counted. Every container connected to a network holds a reference. When you try to delete the network, Docker checks for active endpoints (container connections). If any exist, the deletion fails.

Common causes:

• Containers are still running. You forgot to stop containers before removing the network.
• Stopped containers still attached. Stopped containers maintain their network attachment until they are removed.
• Orphaned endpoints. A container was forcefully killed or Docker crashed, leaving stale network endpoints.
• Docker Compose stale state. A previous docker-compose up created the network, but the compose file changed and docker-compose down cannot clean up properly.
• Multi-compose projects sharing a network. Multiple Compose projects share an external network, and one project’s containers are still attached.

Fix 1: Find and Stop Connected Containers

Identify which containers are using the network:

docker network inspect my-network --format '{{range .Containers}}{{.Name}} {{end}}'

Or for detailed information:

docker network inspect my-network

Look at the Containers section in the JSON output. It lists every container connected to the network.

Stop and remove the containers:

docker stop container1 container2
docker rm container1 container2

Then remove the network:

docker network rm my-network

Pro Tip: Use docker network inspect with jq for cleaner output:

docker network inspect my-network | jq '.[0].Containers | keys[]'

This lists only the container IDs, which you can pipe to docker stop and docker rm.

Fix 2: Disconnect Containers from the Network

If you do not want to stop the containers but just want to free the network, disconnect them first:

docker network disconnect my-network container1
docker network disconnect my-network container2

Then remove the network:

docker network rm my-network

Force disconnect if a normal disconnect fails (e.g., the container no longer exists):

docker network disconnect -f my-network container1

The -f flag forces disconnection even if the container is not running or has been removed.

Fix 3: Fix Stale Endpoints

Sometimes Docker reports active endpoints even though no containers are visibly connected. This happens after crashes, forced kills, or Docker daemon restarts.

Check for ghost containers:

docker network inspect my-network

If the Containers section lists containers that docker ps -a does not show, you have stale endpoints.

Fix: Force disconnect the stale endpoint:

docker network disconnect -f my-network <container-id-from-inspect>

Use the container ID shown in the network inspect output, even if the container no longer exists.

Fix: Restart the Docker daemon:

sudo systemctl restart docker

A daemon restart cleans up stale network state. Warning: This stops all running containers briefly. They restart if they have a restart policy.

If the Docker daemon itself is not running, see Fix: Docker daemon is not running.

Fix 4: Fix Docker Compose Network Issues

Docker Compose creates a default network named <project>_default for each project. Common issues:

Orphaned containers from a previous run:

docker-compose down --remove-orphans

The --remove-orphans flag removes containers from services that are no longer defined in the compose file.

If docker-compose down itself fails:

# Stop all containers in the project
docker-compose stop

# Remove containers
docker-compose rm -f

# Now remove the network manually
docker network rm my-project_default

If the compose file was renamed or moved:

Docker Compose uses the directory name as the project name. If you moved the compose file, the project name changed and docker-compose down cannot find the old containers.

# Specify the old project name explicitly
docker-compose -p old-project-name down

Common Mistake: Running docker-compose down from a different directory than where you ran docker-compose up. The project name is derived from the directory name, so down looks for containers under the wrong project name and cannot find or stop them.

Fix 5: Handle External Shared Networks

When multiple Compose projects share an external network, you cannot remove it until all projects disconnect:

# compose-project-a.yml
networks:
  shared:
    external: true
    name: my-shared-network

# compose-project-b.yml
networks:
  shared:
    external: true
    name: my-shared-network

Find all containers on the shared network:

docker network inspect my-shared-network --format '{{range .Containers}}{{.Name}} ({{.IPv4Address}}){{"\n"}}{{end}}'

Stop all projects using the network:

cd project-a && docker-compose down
cd project-b && docker-compose down

Then remove the network:

docker network rm my-shared-network

Fix 6: Prune Unused Networks

If you have many unused networks and want to clean them all up:

docker network prune

This removes all networks not used by at least one container. Docker asks for confirmation first.

Skip the confirmation prompt:

docker network prune -f

Prune networks older than a certain age:

docker network prune --filter "until=24h"

This removes networks created more than 24 hours ago that are not in use.

Full system cleanup (networks, containers, images, volumes):

docker system prune -a

Warning: docker system prune -a removes everything not currently in use — all stopped containers, all unused images, all unused networks, and all build cache. It does not remove volumes unless you add --volumes. Use with caution. For disk space issues, see Fix: Docker no space left on device.

Fix 7: Fix Network Issues After Docker Upgrade

After upgrading Docker, the network subsystem might have stale state from the old version:

# Check for inconsistencies
docker network ls
docker network inspect bridge

# Restart Docker to reinitialize networking
sudo systemctl restart docker

If specific networks are corrupted, remove and recreate them:

docker network rm my-network
docker network create my-network

For custom networks with specific subnets:

docker network create --subnet=172.20.0.0/16 --gateway=172.20.0.1 my-network

Fix 8: Handle Swarm Mode Networks

In Docker Swarm mode, networks behave differently. Service networks cannot be removed while services use them:

# Check which services use the network
docker service ls --filter "network=my-overlay-network"

# Remove the services first
docker service rm my-service

# Then remove the network
docker network rm my-overlay-network

Force remove a stuck Swarm network:

docker network rm my-overlay-network

If this fails, leave and rejoin the swarm:

docker swarm leave --force
docker swarm init

Warning: Leaving the swarm stops all services and removes all swarm state. Only do this as a last resort.

If Docker containers are having port conflicts instead of network issues, see Fix: Docker port is already allocated.

Still Not Working?

If the network still reports active endpoints after trying all fixes:

Check for containers in other namespaces. Docker Desktop on macOS/Windows uses a VM. Containers might be running inside the VM that are not visible from docker ps:

docker ps -a --format "{{.ID}} {{.Names}} {{.Status}}" | grep -i exit

Check for Kubernetes-managed containers. If Docker Desktop has Kubernetes enabled, Kubernetes creates its own networks and containers. These might hold references to your networks:

docker ps -a | grep k8s

Do not remove Kubernetes-managed containers or networks manually.

Check for Docker daemon bugs. Some Docker versions have bugs where network endpoints are not cleaned up properly. Update Docker:

sudo apt update && sudo apt install docker-ce docker-ce-cli containerd.io

Check iptables rules. Docker manages iptables rules for networking. Corrupted rules can interfere with network operations:

sudo iptables -L -n | grep -i docker

Last resort — reset Docker networking entirely:

sudo systemctl stop docker
sudo rm -rf /var/lib/docker/network
sudo systemctl start docker

This deletes all Docker network state and forces Docker to recreate it from scratch. All custom networks are lost. Only use this if nothing else works.

For container permission issues that might be related to network configuration, see Fix: Docker permission denied socket.