Docker's pool overlap error is not a VPN route problem

Docker refuses to create a network with the message pool overlaps with other one on this address space, and someone decides the VPN route must be the cause. It cannot be. That error is produced while a pool is being allocated, before a single packet exists, and a manual kernel route has no bearing on it. The VPN matters one step later, when a container that already has an address stops being reachable after a route appears. Two problems, two sets of evidence, and mixing them produces a change that fixes neither.

Two errors that look alike

The allocation error is arithmetic. Docker compares the subnet you asked for with the subnets it already manages, finds an intersection, and refuses. Nothing is running yet, so there is no route, no container and no traffic to inspect.

The runtime symptom is a reachability question. A container that answered yesterday does not answer now, and something changed on the host's routing table. The container still holds its address; the question is which path that address takes.

Both are address-plan problems. Only one of them is a Docker problem.

Read the allocated pools first

List the networks and inspect the ones that could intersect. The subnet lives in the IPAM configuration, and the attached containers are listed separately:

docker network ls
docker network inspect EXISTING_NETWORK

Compare that subnet with the pool the new network requests, and remember that Compose creates its own default network per project. A conflict with a project you forgot about looks exactly like a conflict with the daemon.

A static ipv4_address on a service is one container's address, not the pool definition. Changing it does not remove an overlap, because the overlap is between network subnets rather than between containers. Docker's network-create reference requires non-overlapping subnets for ordinary bridge allocation and documents how to select one explicitly.

Pick a prefix that survives the VPN

The immediate conflict and the future route are decided by the same choice, so make it once. Compare the candidate range with the LAN, with every VPN destination the host can reach, and with any other overlay in use.

A prefix that satisfies Docker and collides with the remote network gives you a container that starts cleanly and becomes unreachable the moment the tunnel is up. That is the second error in this article, and it is much harder to diagnose later than it is to avoid now.

Write the chosen ranges down somewhere the next project can read them. A one-line register of allocated prefixes is cheaper than a week of unexplained timeouts.

Retire or change a network deliberately

For a new Compose network, set the unused prefix in the network's IPAM configuration. For an existing project, plan the renumbering: fixed addresses, dependent services and the network recreation step all have to be accounted for, because editing YAML does not renumber a running network.

If an obsolete network owns the conflicting allocation, inspect who is attached before removing it. docker network rm refuses while active endpoints exist, and docker stop takes container names or IDs rather than a network name. Stopping a container also does not remove the network definition that holds the pool.

A broad prune is not a diagnostic tool. It reaches unrelated projects and destroys the evidence you were about to collect.

Default pools help only the next allocation

The daemon's default address pool setting improves future automatic allocations by keeping them out of ranges you reserve. It does not retroactively readdress networks that already exist, and it does not resolve an explicit subnet that overlaps another explicit subnet.

Treat that setting as a separate, planned change with its own restart, not as part of repairing one project. Mixing the two means a daemon restart lands in the middle of an unrelated investigation. Schedule it in its own window. Then confirm one new automatic allocation actually lands outside the ranges you reserved.

Once creation succeeds, verify the subnet that is actually running and then make one real application request with the VPN in its intended state. If the pool is valid and access still fails, the remaining work is route selection, filtering and the return path. That is a runtime investigation, and it does not retroactively make the allocation error meaningless.

Order of work: read the allocated pools, choose a prefix that clears both Docker and the VPN destinations, recreate the network deliberately, then test one request with the tunnel up.