How to fix "Cannot remove network: resource is busy" (active endpoints)

What this error means

Docker refuses to delete a network if any endpoint is still attached. Endpoints come from containers, Compose projects, or Swarm services using that network. You must disconnect or remove those endpoints first.

Typical message: Cannot remove network <name>: resource is busy

Quickstart (one network)

1. Set the network name.
2. List and remove containers attached to it.
3. Remove the network.

NET=my_net
# Show what is using the network
docker ps -a --filter network="$NET"

# Option A: disconnect containers without removing them
for c in $(docker ps -aq --filter network="$NET"); do
  docker network disconnect -f "$NET" "$c"
done

# Option B: stop and remove containers (releases endpoints)
# docker rm -f $(docker ps -aq --filter network="$NET")

# Remove the network
docker network rm "$NET"

Minimal working example

Reproduce the error, then fix it.

# Create a user network
docker network create demo_net

# Start a container attached to it
docker run -d --name demo_nginx --network demo_net nginx:alpine

# Try to remove the network (will fail)
docker network rm demo_net
# -> Error response from daemon: network demo_net id ... has active endpoints

# Fix: detach the endpoint, then remove
docker network disconnect demo_net demo_nginx
# or: docker rm -f demo_nginx

docker network rm demo_net

Step-by-step: diagnose and resolve

1. Identify containers/services using the network

   • List containers by network:

     docker ps -a --filter network=<network>
     

   • Inspect the network to see attached containers:

     docker network inspect <network>
     # Look under "Containers" for IDs and names
     

2. Disconnect or remove the users of the network

   • Disconnect without deleting containers:

     docker network disconnect <network> <container>
     # Force if needed
     docker network disconnect -f <network> <container>
     

   • Or stop/remove containers:

     docker rm -f <container>
     

3. Handle Docker Compose projects

   • Compose creates project-scoped networks (e.g., myapp_default). Tear down the project to release the network:

     # From the compose directory
     docker compose down
     # Also remove volumes and orphaned services if appropriate
     docker compose down -v --remove-orphans
     

   • If the network is external in compose.yaml, remove or disconnect containers that reference it, not the Compose network itself.

4. Handle Swarm or overlay networks

   • Services attach tasks to networks; remove the services first:

     docker service ls
     docker service ps <service>
     docker service rm <service>
     # Or remove the entire stack
     docker stack rm <stack>
     

   • Re-try network removal from a Swarm manager node:

     docker network rm <network>
     

5. Clean up dangling networks

   • After all endpoints are gone:

     docker network prune
     # Confirm prompt, or use: docker network prune -f
     

6. If endpoints seem orphaned

   • Restart the Docker engine to clear stale state, then retry:

     # Linux
     sudo systemctl restart docker
     # macOS/Windows (Docker Desktop): restart the app
     

   • Re-run inspect and disconnect/remove as above.

Common scenarios and commands

• Find everything attached to a network:

  docker ps -a --filter network=<network>
  docker network inspect <network>
  

• Detach all containers from a network:

  for c in $(docker ps -aq --filter network=<network>); do
    docker network disconnect -f <network> "$c"
  done
  

• Remove all stopped containers (often holding endpoints):

  docker container prune
  

• Compose teardown (releases networks it created):

  docker compose down
  

• Swarm teardown (releases overlay networks):

  docker stack rm <stack>
  

Choosing the right fix

Pitfalls

• Stopped containers still block network removal. Remove or disconnect them.
• Compose-created networks often end with _default. Removing them manually while the project exists will fail; use docker compose down.
• Overlay networks are cluster-scoped. Remove services/stacks across the Swarm before removing the network on a manager node.
• Multiple networks with similar names: prefer IDs or double-check names via docker network ls.
• Prune commands are destructive. Ensure you understand what will be deleted before confirming.

Performance notes

• Inspecting networks and listing containers are lightweight operations; prefer them to broad prunes.
• Disconnecting many containers in a loop scales linearly with container count. Use batched rm -f when safe to reduce shell loops.
• Removing large overlay networks may take seconds due to cluster coordination; perform removals from a manager and avoid concurrent churn (rolling deploys) on the same network.
• Frequent create/delete cycles: use ephemeral networks only when needed; reusing a stable network avoids repeated allocations.

Tiny FAQ

• Can I force-remove a Docker network in one command? No. There is no force flag that bypasses active endpoints. You must disconnect or remove the containers/services first.

• Does stopping containers free the network? Not necessarily. A stopped container can still keep its endpoint; remove the container or disconnect it from the network.

• How do I find which Compose project created a network? Inspect the network; look for Labels like com.docker.compose.project and com.docker.compose.network.

• I removed all containers but still get the error. What next? Restart the Docker engine to clear stale state, then re-check with docker network inspect. In Swarm, ensure no services/tasks still reference the network.

• Is docker network prune safe? It removes all unused networks. Only run it if you are certain no running workloads rely on unused networks.