“Network Has Active Endpoints” Error While Removing Network in Docker

1. Overview

Docker has revolutionized how developers build, share, and run containerized applications. Yet even as it streamlines workflows, users occasionally encounter cryptic errors. Regularly, it involves understanding how Docker’s components interact, particularly when cleaning up after use. When running the rm command, one of the most common errors is “Network has active endpoints“.

Despite intentions to tidy up, Docker prevents the removal because the network still has “active endpoints.” In this tutorial, we dig into what Docker networking entails, what endpoints are, why they linger, and the steps we must take to resolve this commonly encountered error. We’ll cover not only the commands but the rationale behind them, with real-world examples and best practices.

2. What Are the Endpoints Common Errors?

In Docker terminology, an endpoint is the connection point between a container and a network. Closely, we think of it like a virtual cable plugging a container into the virtual switch. Let’s see how to run an endpoint and assign it a name and network in a single prompt:

# docker run -d --name my_app1 --network my_bridge_net nginx

Next, let’s break down the steps that follow this command in the background:

• The container my_app1 starts
• Docker assigns it an IP
• Docker adds a network interface
• Docker wires it into my_bridge_net

Behind the scenes, Docker uses a bridge network driver by default for standalone containers. This driver creates an isolated subnet that allows containers to communicate. Let’s create a custom network:

# docker network create my_bridge_net

Docker sets up a virtual switch, assigns a subnet, and enables containers attached to this network to communicate using virtual Ethernet interfaces inside the containers. The moment a container joins this network, it creates an endpoint by plugging into this virtual topology.

In addition, it’s important to understand the lifecycle of the endpoint, its creation, and its termination.

Endpoints are created when containers are attached to networks. Notably, they persist until one of two conditions is met:

• The container is removed using the docker rm command
• The container is disconnected from the network using the docker network disconnect command

Furthermore, stopping a container (docker stop) does not remove the endpoint. Consequently, that lingering endpoint often causes the “network has active endpoints” issue.

However, the question remains: Why do Endpoints Impact Network Removal? The answer to this is that Docker prohibits deleting a network with active endpoints. This safeguard prevents disrupting live connections or network assignments, which could cause data loss or instability. Hence, attempting to remove such a network fails with the error “network has active endpoints “.

3. Identifying Potential Root Causes

Now, we’ll move forward with identifying the root cause of this common error. Let’s use the rm command to remove my_bridge_net:

# docker network rm my_bridge_net
Error response from daemon: error while removing network: network my_bridge_net id <hash>: network has active endpoints

In this section, the aim is to help parse the error, understand the culprits, and help diagnose the problem to find the root cause quickly.

3.1. Unpacking the “network has active endpoints” Error

First, let’s attempt to remove an instance my_bridge_net using the rm command:

# docker network rm my_bridge_net

Next, let’s parse the error:

Error response from daemon:
error while removing network: network <network-name> id <hash>: network has active endpoints

Docker identifies one or more containers still connected via endpoints—even if they no longer run. Hence, this is why it is mandatory to understand the common causes:

• Stopped (but not removed) containers: Containers can remain inactive but still connected
• Orphaned containers from Docker Compose: Compose sometimes leaves old containers behind due to configuration changes
• Manual container creation on shared networks: Overlapping network usage can result in unexpected endpoint attachments

Understanding this makes the error message clearer and highlights a better signal of what needs attention.

3.2. Identifying the Culprits

To identify the culprit, we need to inspect the network to determine what’s attached by using the network inspect command:

# docker network inspect \
  --format '{{range $cid,$v := .Containers}}{{printf "%s: %s\n" $cid $v.Name}}{{end}}' \
  my_bridge_net

e5f1a3c84b3b: my_app1
9d8c7b6a5f4e: my_app2

From the output, we can detect a key insight: There are containers still linked to our network, namely my_app1 and my_app2. Finally, we have the targets for resolution.

4. Resolving the Error

In this section, we’ll go over different methods to resolve this issue.

4.1. Stop and Remove Containers

The first method we’ll cover is to stop and remove all containers:

# docker container stop my_app1 my_app2
# docker container rm my_app1 my_app2

After stopping and removing the containers,  we attempt again to remove the network my_bridge_net:

# docker network rm my_bridge_net

This is the most thorough fix. We guarantee success when we can remove the containers.

4.2. Disconnecting Containers Without Removing

In case we want to preserve a container’s state, instead of stopping it and removing it, we can disconnect it from the network:

# docker network disconnect -f my_bridge_net my_app1
# docker network disconnect -f my_bridge_net my_app2
# docker network rm my_bridge_net

The forced disconnect removes the endpoint cleanly.

4.3. Restarting Docker Daemon

On rare occasions, when all else fails, an endpoint may persist even after container removal; that is, a ghost endpoint. In this case, we restart Docker as this might be the quickest and most useful method to use, as it resets its internal state:

# On Linux systems
$ sudo systemctl restart docker

# Verify daemon is back online
$ docker info

# Retry network removal
$ docker network rm my_bridge_net

This sequence of actions involves restarting the Docker service on a Linux system, followed by verifying its operational status. Once confirmed, the final step is to remove a specified Docker network. Essentially, it’s a troubleshooting measure to ensure Docker is functioning correctly before attempting to delete a network that might have been causing issues.

5. Troubleshooting Compose

This section observes how we might apply the above strategies in real production use cases.

5.1. Docker Compose Network Leak

In other situations, if our system administrator uses the Docker compose command, this may result in unidentified problems.

When using Docker Compose, it often creates a default network named <project>_default. We’ll often remove this infrastructure with docker-compose down:

# docker compose down

However, even after running the command above, Compose can sometimes leave behind network endpoints.

To address this, we can add the remove-orphans option:

# docker compose down --remove-orphans
# docker network rm <project>_default

This ensures that all containers—both named and orphaned—are removed, and no stray endpoints remain.

Interestingly, Compose relies on user-defined bridge networks similar to the default bridge driver. These behave like isolated virtual switches, and Docker wires containers through endpoints just like in manual setups. Nevertheless, we use compose down in a situation where the network is defined externally from the compose file.

We shouldn’t always use –remove-orphans when removing network endpoints in containers because it can unintentionally remove containers from other projects that share the same network but aren’t defined in the current Compose file.

5.2. Jenkins Pipeline Network Cleanup Issue

Finally, if we often use Jenkins, we might run into Jenkins pipeline network Cleanup issues.

Let’s imagine a Jenkins script that takes down its CI infrastructure in the following way:

# docker compose down
# docker network rm my_bridge_net

If our script gets the “network has active endpoints” error, we can apply what we’ve learned already to remove orphans. That is, we can add the –remove-orphans flag:

# docker compose down --remove-orphans
# docker network rm my_bridge_net

Though note that if this is happening consistently, we may want to investigate first using our other diagnostic measures.

To resolve the issue, we update the pipeline script to inspect the network and automatically remove any lingering endpoints before attempting to delete the network. Accordingly, this makes the cleanup process deterministic and reliable.

6. Strategies for Prevention

6.1. Compose Orphans and Shared Networks

In some CI/CD setups, Docker Compose can mistakenly manage shared or pre-existing networks, leading to unexpected conflicts during orchestration. Hence, a simple fix is to define the network as external in our docker-compose.yml:

networks:
  my_bridge_net:
    external: true

This tells Compose to use the existing network without trying to create or delete it, thus preventing accidental reuse or destruction.

6.2. Avoiding Network Reuse in CI Pipelines

If multiple pipeline runs share a static network name, collisions and race conditions can occur, especially in parallel executions. Accordingly, the best practice would be to use dynamic naming for networks:

# network_name: myapp_${GIT_COMMIT}

Here, we inject a unique identifier (like the Git commit hash) into the network name, avoiding overlap between concurrent jobs and eliminating the need for manual cleanup.

7. Conclusion

In this article, we addressed the common Docker error: “network has active endpoints.” This error occurs when we try to remove a Docker network that still has connected containers. In addition, we explained the fundamentals of Docker networking and what endpoints are. From there, we showed how to identify the containers causing the issue.

To fix it, we covered how to stop and remove containers, disconnect them forcefully, or restart the Docker daemon. Finally, we also provided practical advice for managing Docker Compose networks and CI pipelines.