🚨 Docker Error Guide: 'Pool overlaps with other one on this address space' — Subnet Collision

Overview

Docker assigns each user-defined network a private IPv4 subnet. When you create a network with an explicit subnet that overlaps an already-allocated one — or two Compose projects request overlapping CIDRs — the daemon refuses to allocate the address space:

Error response from daemon: Pool overlaps with other one on this address space

It appears on docker network create --subnet ..., on docker compose up when a network’s ipam config collides, and sometimes after adding a custom subnet to an existing stack.

Symptoms

• docker network create --subnet 172.20.0.0/16 ... fails while a similar-looking network already exists.
• docker compose up fails to create a project network that declares a fixed subnet.
• Two teams’ stacks both start fine alone but conflict when run on the same host.
• The error persists even after docker network rm, because a leftover network still owns the range.

Common Root Causes

• Two networks request overlapping subnets — e.g. 172.20.0.0/16 and 172.20.5.0/24 overlap.
• A stale network still owns the range — a previous stack was not fully removed and its network still holds the CIDR.
• The requested subnet overlaps the default bridge pool — Docker’s default address pools (often 172.17.0.0/16 upward) collide with your custom choice.
• A host route or VPN uses the same range, and you configured Docker’s default-address-pools to avoid it, narrowing what is available.
• Duplicate ipam blocks across Compose files — an override file re-declares the same subnet.

Diagnostic Workflow

List every network and reveal which subnets are already taken:

docker network ls
for n in $(docker network ls -q); do
  docker network inspect -f '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' "$n"
done

Inspect the specific network you think collides:

docker network inspect bridge
docker network inspect myapp_backend

Confirm the subnet Compose is requesting:

docker compose config | grep -A6 ipam

Check whether a host route already claims the range:

ip route | grep 172.20

Review daemon logs for the allocation failure:

journalctl -u docker --since '15 min ago' | grep -i 'overlap\|pool'

Example Root Cause Analysis

A CI host ran multiple isolated stacks. A new stack pinned its network to 172.20.0.0/16 in docker-compose.yml. docker compose up failed with Pool overlaps with other one on this address space. Enumerating subnets showed:

proja_default 172.20.0.0/24

The existing proja_default used 172.20.0.0/24, which the new /16 request fully encompassed — a strict overlap even though the older network was smaller. Rather than widen or move the existing network, the new stack was changed to a clearly separate range in its Compose IPAM config:

networks:
  backend:
    ipam:
      config:
        - subnet: 10.89.0.0/24

docker compose up then allocated cleanly. The takeaway: overlap checks compare ranges, not exact strings — a /16 and a /24 inside it collide.

Prevention Best Practices

• Assign each stack a distinct, documented /24 (or larger) from a planned address plan so ranges never intersect.
• Prefer letting Docker auto-assign subnets unless you have a concrete reason to pin them.
• If you must pin, configure daemon-wide default-address-pools in /etc/docker/daemon.json and carve project subnets from disjoint blocks.
• Avoid ranges that collide with corporate VPNs or host routes (check ip route first).
• Fully remove old stacks (docker compose down) so their networks release the CIDR before reusing it.

Quick Command Reference

# Dump every network's subnet
for n in $(docker network ls -q); do \
  docker network inspect -f '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' "$n"; done

docker network inspect bridge          # default pool in use
ip route | grep 172.                    # host routes that could collide
docker network create --subnet 10.89.0.0/24 backend
docker compose down                     # release a stack's subnet

Conclusion

This error is a subnet collision: the CIDR you requested overlaps a range Docker has already allocated, even if the two masks differ in size. Enumerate existing subnets, pick a disjoint block, and pin it in your Compose ipam config or daemon.json. Planning an address scheme up front and tearing stacks down cleanly keeps ranges from colliding. Explore more networking fixes in the Docker guides.