How to fix ERROR: Pool overlaps with other one on this address space in Docker

First, identify all existing Docker networks and their subnets:

docker network ls

Then inspect each network to see its subnet configuration:

docker network inspect <network_name>

Look for the "Subnet" field in the IPAM Config section. You can also list all subnets at once:

docker network inspect $(docker network ls -q) | grep -E '"Name"|"Subnet"'

Compare the subnet from the error or your docker-compose.yml with existing networks. Look for networks with matching IP ranges.

You can also check which network interfaces on your host might be conflicting:

ip addr show | grep "inet "

On macOS:

ifconfig | grep "inet "

Note: Network IDs starting with br- in ip addr output correspond to Docker networks (e.g., br-7bf61cfc0b5a means Docker network ID 7bf61cfc0b5a).

If you identified an unused Docker network causing the conflict, remove it:

docker network rm <network_name>

If containers are still connected to the network, stop them first:

docker stop $(docker network inspect <network_name> -f '{{range .Containers}}{{.Name}} {{end}}')
docker network rm <network_name>

For a clean slate, you can remove all unused networks:

docker network prune

Warning: This removes all networks not used by at least one container.

If your docker-compose.yml specifies a conflicting subnet, change it to a non-overlapping range:

networks:
  my_network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/16  # Use a different subnet

Choose a subnet that doesn't conflict with:
- Other Docker networks (check with docker network inspect)
- Your host's network interfaces
- Your VPN's IP range
- Common private ranges: 10.x.x.x, 172.16-31.x.x, 192.168.x.x

If you want multiple docker-compose projects to share a network, create it once and reference it as external:

First, create the network:

docker network create shared_network

Then reference it in docker-compose.yml:

networks:
  my_network:
    external: true
    name: shared_network

This prevents Docker from trying to create a new network each time.

If the error started after connecting to a VPN, the VPN may be using Docker's default IP ranges. Temporarily disconnect:

# OpenVPN
sudo systemctl stop openvpn

# Or kill the VPN process
sudo killall openvpn

Then retry your Docker command. If this works, see the Advanced Notes for permanent solutions.