docker compose up fails with 'Pool overlaps with other one on this address space'
Pool overlaps with other one on this address spaceShort 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.
Fix it fast
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)2Match what you see, then jump to its fix
- 1
Pool 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
The same ipam subnet appears in two compose files, and the second one to start failsTwo projects declare the same fixed subnetFix - 3
The 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
- 1
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 ls2Fix
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 prune3Verify
Start the project again.
docker compose up -dConfirmed by docs.docker.com
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/163Verify
Both projects start together.
docker compose up -d && docker network lsConfirmed by docs.docker.com
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 ls2Fix
Replace the ipam block with an external network and point it at the existing name.
networks:
default:
name: my-shared-net
external: true3Verify
Compose starts and the service gets an address on that network.
docker compose up -d
docker network inspect my-shared-netConfirmed by docs.docker.com
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
Servers
Docker Compose runs out of address pools for new networks
ERROR: could not find an available, non-overlapping IPv4 address pool among the defaults to assign to the network
Docker hands every new network a subnet from its default address pools.
3 causes, each with a fixServers
docker compose down leaves the default network behind
Network myproject_default Resource is still in use
Compose only removes a project network when no container is attached to it.
3 causes, each with a fixServers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fix