Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker compose up fails with 'Pool overlaps with other one on this address space'

ErrorPool overlaps with other one on this address space

Short answer

The compose file asks for a fixed subnet that another Docker network already uses, and a bridge network cannot share it. Find the network holding that subnet. Remove it if nothing needs it, or give your project a different subnet. Leftover networks from earlier runs are the usual owner.

  • Applies to Docker Engine 28, Docker Compose v2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List every network and print the subnet it holds. The one that matches the subnet in your compose file is the conflict.

    docker network ls
    docker network inspect --format json $(docker network ls -q)
  2. 2Match what you see, then jump to its fix

    1. 1Pool overlaps with other one on this address space, right after you stopped or renamed a projectA network from an earlier project still holds the subnetFix
    2. 2The same ipam subnet appears in two compose files, and the second one to start failsTwo projects declare the same fixed subnetFix
    3. 3The subnet you wrote is the subnet of a network you made by hand with docker network createThe project should join a network that already existsFix

What does the error look like?

  • Pool overlaps with other one on this address space

Cause 1 of 3

A network from an earlier project still holds the subnet

1Check

Docker refuses to create a network whose subnet overlaps an existing one. A network left behind by an old project, or by a project with another name, keeps its subnet until it is removed.

docker network ls

2Fix

Stop the old project so Compose removes its networks, or prune networks that no container uses. Pruning asks for confirmation and never touches bridge, host or none.

docker compose down
docker network prune

3Verify

Start the project again.

docker compose up -d

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

Two projects declare the same fixed subnet

1Check

A bridge network takes one subnet, and overlapping subnets make network creation fail. Look for the same subnet in every compose file on the host.

grep -rn "subnet" --include=docker-compose*.yml --include=compose*.yaml .

2Fix

Give each project its own subnet in the ipam block, or remove the subnet line and let Docker choose a non-overlapping one.

networks:
  default:
    ipam:
      config:
        - subnet: 172.28.0.0/16

3Verify

Both projects start together.

docker compose up -d && docker network ls

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The project should join a network that already exists

1Check

Compose can attach to a network it did not create. Marked external, Compose does not create it, and it fails if the network is missing.

docker network ls

2Fix

Replace the ipam block with an external network and point it at the existing name.

networks:
  default:
    name: my-shared-net
    external: true

3Verify

Compose starts and the service gets an address on that network.

docker compose up -d
docker network inspect my-shared-net

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Run docker compose down when you finish with a project so its networks are released.
  • Keep one list of the subnets you use by hand, per host, and never reuse one.
  • Prefer the automatic subnet unless something outside Docker needs a fixed range.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.