Fixing Docker Address Pool and Network Overlap Errors on Pterodactyl Wings

Your Pterodactyl panel worked yesterday. Today, creating or starting a server fails and Wings logs one of these:

could not find an available, non-overlapping IPv4 address pool among the defaults to assign to the network

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

On a node that has been rebooted or updated, you may see this one instead:

failed to create endpoint on Docker network: Error response from daemon:
network pterodactyl_nw already has active endpoints

The first two are Docker refusing to hand out a subnet. The third is a stale network that will not get out of the way. In every case the container never starts, and the reason behind the message decides which fix you apply.

Which Error Do You Have

There are two root causes that produce almost identical symptoms.

Exhaustion. Docker has used up its default pool. Each container network eats a whole subnet, and after enough servers there is nothing left to allocate. The message usually mentions not finding an available pool "among the defaults". This shows up on established nodes that have been running for months.

Collision. The range Docker wants is already in use by something else on the host, so Docker refuses to create a bridge on top of it. The message usually reads "Pool overlaps with other one on this address space". This shows up on brand new nodes, on the very first server you try to create, or right after a network change on the host.

A quick way to tell them apart:

docker network ls | wc -l

Dozens of networks on a busy node point at exhaustion. A near empty list on a fresh node points at a collision with the host's own routing.

Why Docker Runs Out of Address Space

Docker assigns each container network a subnet from a pool of private ranges, by default carving /24 blocks out of 172.16.0.0/12. A /24 holds 254 usable addresses, and a game server container needs a handful of them at most. The rest is wasted, and the pool empties far faster than the raw address count suggests.

On a Pterodactyl node with a lot of game servers, that adds up quickly. After roughly 30 to 50 container networks the default pool is dry and Docker has nothing left to allocate. Servers that are created and deleted often make it worse, because networks left behind by deleted servers still hold their subnet.

Why Docker Says the Pool Overlaps With Another One

The other case is a straight address conflict. Docker creates virtual bridges for container communication, and when Wings starts a server it asks Docker to attach that container to an internal bridge. If a subnet Docker wants is already routed on the host, the bridge cannot be created.

Common sources of the conflict:

• The machine sits behind a private management or internal network that already uses part of 172.16.0.0/12
• A VPN on the host, WireGuard or OpenVPN, brings up a tunnel in an overlapping range
• Another Docker application on the same box, such as Nginx Proxy Manager, Portainer or a database stack, already claimed the subnet
• The host's default gateway or a secondary interface sits inside 172.20.0.0/16

Diagnosing the Conflict

Start with the host's interfaces and routing table:

ip addr show
ip route show

Look for anything in the 172.16.0.0 through 172.31.255.255 range and note which interface owns it.

Then list what Docker already has:

docker network ls
docker network inspect bridge

The inspect output shows each network's subnet under IPAM.Config. If a Docker network is sitting on 172.18.0.0/16 and an internal management interface on the host is also on 172.18.x.x, that is your conflict.

Fix 1: Move Docker Off the Conflicting Range

If the problem is a collision, point Docker somewhere nothing else is using. Edit or create /etc/docker/daemon.json:

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

Docker now allocates container bridges out of 10.100.0.0/16 instead of the 172.x.x.x range, with each bridge getting a /24 and its 254 usable addresses.

Pick a base that does not collide with any of the following:

• The server's own public and private addresses
• A private or management network the machine is attached to
• Your VPN subnet
• Networks belonging to other Docker applications on the box

Restart Docker, then Wings:

sudo systemctl restart docker
sudo systemctl restart wings

Restarting Docker stops every container on the host, so do it in a maintenance window if the node has players on it.

Fix 2: Give Docker More Subnets to Hand Out

If the problem is exhaustion, the answer is a bigger pool cut into smaller pieces:

{
  "default-address-pools": [
    {
      "base": "172.17.0.0/12",
      "size": 28
    }
  ]
}

Two things change here:

1. base widens the range Docker draws from, from a /16 with 65,536 addresses to a /12 with 1,048,576
2. size: 28 makes each container network a /28 with 16 addresses instead of a /24 with 256. Game server containers do not need 256 addresses each

That combination scales to thousands of container networks rather than a few dozen. Restart Docker and Wings the same way as above.

Picking Numbers That Cover Both Problems

If you are on a busy node and the 172 range is contested, do both at once. Move the base somewhere clear and shrink the block size:

{
  "default-address-pools": [
    {
      "base": "10.100.0.0/16",
      "size": 28
    }
  ]
}

A /16 carved into /28 blocks gives 4,096 networks, which is more than any single node is likely to need. default-address-pools takes a list, so you can add a second entry on a different base if you ever want to keep two ranges separated.

Cleaning Up Old and Conflicting Networks

Changing the pool does not reclaim subnets that are already spoken for. Networks left over from deleted servers or old container instances keep holding their allocation until you remove them:

# See what exists
docker network ls

# Remove one network, only if nothing is using it
docker network rm pterodactyl_nw

# Remove everything not attached to a running container
docker network prune

If docker network rm refuses with network pterodactyl_nw already has active endpoints, something is still attached to it, often a container that did not shut down cleanly. Check what is holding it:

docker network inspect pterodactyl_nw

The Containers section lists the endpoints. Stop those containers, then remove the network. Wings recreates its own networks with the current configuration the next time a server starts.

Pruning on its own is enough to get a node running again in a hurry, but it is a temporary fix. Without a pool change, the same node fills up again as you add servers.

The Nginx Proxy Manager Conflict

A specific and common version of the overlap problem happens when Nginx Proxy Manager runs on the same host as Wings. NPM creates its own Docker networks during setup, and those networks tend to claim subnets in the 172.20.x.x or 172.21.x.x range. When Wings later asks for a network of its own, Docker finds the range taken and throws the overlap error.

The daemon.json fix handles the Wings side. To keep the two from drifting back into each other, give NPM an explicit subnet in its docker-compose.yml:

networks:
  default:
    ipam:
      config:
        - subnet: 10.200.0.0/24

Now NPM has a fixed /24 that sits outside whatever pool Docker hands to Wings.

Port 443 and the Wings Websocket

Running NPM next to Wings brings a second, separate problem. NPM listens on 443 for HTTPS. Wings also wants 443 for the secure websocket between the node and the panel. Whichever starts first takes the port, and if that is NPM, Wings cannot bind its listener. The panel then shows the node as offline even though Wings is running fine.

Three ways out:

1. Move Wings to another port. In /etc/pterodactyl/config.yml, change api.port to something like 8443, then update the node's configuration in the panel to match.
2. Put Wings behind NPM. NPM can proxy websocket traffic. Create a proxy host for the node's hostname pointing at the Wings listener, and let NPM terminate TLS while passing the websocket through.
3. Separate the machines. Once the config gymnastics start costing you more time than the box saves, Wings belongs on a dedicated node with no other web services competing for ports.

Keeping Host Ports and Game Server Ports Apart

Even without NPM in the picture, restarting Docker can surface port clashes between game servers and whatever else runs on the host. If the panel's web server holds 80 and 443 and Docker publishes a container mapping onto the same ports, the panel drops off the network.

Define explicit allocation ranges for your node rather than letting anything grab whatever is free, and make sure Nginx or Apache bind to a specific IP instead of 0.0.0.0 when Docker is also publishing ports on that machine.

Confirming the Fix

Create a server through the panel and watch Wings while it happens:

journalctl -u wings -f

A clean run shows the container being created and started, with no network errors in between. Then confirm the new network landed where you told it to:

docker network ls
docker network inspect $(docker network ls -q | head -1)

IPAM.Config.Subnet should now show an address from the pool you configured, not from the range that was conflicting.

Apply It Before You Need It

Both versions of this error are predictable. A fresh install with five game servers will never hit the exhaustion limit, and a node on a plain public network will never hit the collision. A busy node with 50 or more servers, or any machine sharing an address range with a VPN or an internal network, will eventually run into one of them, usually at the worst possible moment.

Set default-address-pools when you build the node rather than at two in the morning with players waiting. It costs one file and one Docker restart on an empty machine, and it is a much larger job once the node is full.

Space-Node handles Docker networking and node configuration on the servers we host, so this is not an error our customers have to chase. If you are running your own panel, the daemon.json change above sorts it permanently. If you would rather not run the node yourself, our Minecraft plans and VPS hosting come with the networking already sorted.