🚨 Docker Error Guide: 'could not find an available, non-overlapping IPv4 address pool' — Exhausted Subnets

Overview

Docker allocates each user-defined network an automatically chosen subnet from its default address pools. When every candidate pool is already used — by other Docker networks or by host routes — the daemon has nowhere to place a new network and fails:

Error response from daemon: could not find an available, non-overlapping IPv4 address pool 
among the defaults to assign to the network

It appears on docker network create (without an explicit subnet) and on docker compose up when a project needs a new network.

Symptoms

• docker compose up fails to create a project network on a busy host.
• docker network create backend fails even though no --subnet was requested.
• The host has accumulated dozens of networks from repeated up/down cycles.
• Removing a few old networks makes the error disappear.

Common Root Causes

• Leftover networks exhausted the pool — many CI runs or Compose projects created networks that were never removed, consuming every default /16-derived block.
• Host routes overlap the default pools — a VPN or corporate route occupies 172.x ranges Docker would otherwise use, shrinking availability.
• Too-narrow default-address-pools — a custom pool config in daemon.json provides too few subnets.
• Orphaned Compose networks — --remove-orphans was never used, so old project networks linger.
• Large pool size per network — each network consuming a big block drains the pool quickly.

Diagnostic Workflow

Count how many networks exist and how many subnets are consumed:

docker network ls
docker network ls -q | wc -l

Dump each network’s subnet to see the pool exhaustion:

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

Check the configured default pools:

docker info | grep -i 'Default Address Pools' -A3
cat /etc/docker/daemon.json 2>/dev/null

Confirm host routes that could block ranges:

ip route

Prune unused networks to reclaim pools:

docker network prune

Example Root Cause Analysis

A CI runner failed intermittently with could not find an available, non-overlapping IPv4 address pool among the defaults. Each pipeline ran docker compose up in a fresh project but occasionally exited without docker compose down, leaving the project network behind. Over a day, docker network ls -q | wc -l climbed past 30. Each network took a /16-derived slice from the default pool, and Docker’s default address space ran out.

The immediate fix reclaimed the pools:

docker network prune -f

The durable fix had two parts. First, pipelines were changed to always docker compose down --remove-orphans in a cleanup step. Second, the daemon was given more, smaller pools in /etc/docker/daemon.json so many more networks could coexist:

{
  "default-address-pools": [
    { "base": "10.99.0.0/16", "size": 24 }
  ]
}

A /24 size yields 256 networks from a single /16 base, far more than the coarser defaults. After sudo systemctl restart docker, the runner stopped exhausting the pool.

Prevention Best Practices

• Always tear down Compose projects with docker compose down --remove-orphans so their networks are freed.
• Schedule docker network prune -f on shared/CI hosts to reclaim orphaned networks.
• Configure default-address-pools with a small size (e.g. /24) so each base yields many networks.
• Avoid overlapping Docker’s default ranges with VPN or host routes; move Docker’s pools to a free block if needed.
• Monitor network count on busy hosts and alert before the pool is exhausted.

Quick Command Reference

docker network ls -q | wc -l                    # how many networks exist
for n in $(docker network ls -q); do \
  docker network inspect -f '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' "$n"; done
docker info | grep -i 'Default Address Pools' -A3
docker network prune -f                          # reclaim unused pools
docker compose down --remove-orphans             # free a project's network

Conclusion

This error means Docker’s default address pools are fully consumed — usually by orphaned networks piling up, sometimes by host routes shrinking the available space. Prune unused networks to recover immediately, then prevent recurrence by tearing projects down cleanly and configuring more, smaller pools via default-address-pools. For more networking guidance, see the Docker guides.