Docker Address Pools

Every isolated network on a Docker host consumes a subnet from a fixed set of address pools. Trailer creates such networks as part of normal operation, so busy hosts can run out. This page explains when that happens, how to recognize it, and how to raise the limit.

Why Trailer creates networks

Beyond the networks you create yourself, Trailer provisions an isolated bridge network for each workspace URL. This is deliberate: the proxy that serves a URL joins the workspace over a private network of its own, so two workspaces never share a path they could use to reach each other. A host serving many workspaces with URLs therefore holds many small networks at once, and each one claims a subnet from Docker’s address pools.

The symptom

Docker’s default configuration provides roughly 31 subnets for bridge networks. When they are exhausted, new networks cannot be created, and a workspace that needs one will fail to deploy. The workspace enters an error state, and its log contains a message from Docker like:

all predefined address pools have been fully subnetted

Anything else on the same host that creates Docker networks (other tools, compose projects, CI runners) draws from the same pools, so the limit is shared across everything the daemon runs.

Raising the limit

The pool set is configured in the Docker daemon’s configuration file, /etc/docker/daemon.json (create the file if it does not exist). The default-address-pools key lists the address ranges Docker may carve subnets from, and the size field sets the prefix length of each carved subnet. Smaller subnets mean many more networks:

{
  "default-address-pools": [
    { "base": "172.17.0.0/12", "size": 20 },
    { "base": "10.100.0.0/15", "size": 24 }
  ]
}

This example yields several hundred subnets, each still large enough for any workspace network. Apply the change by restarting the daemon:

sudo systemctl restart docker

Two things to check before you apply it:

• Route collisions. The ranges you list must not overlap networks your host actually needs to reach, such as your LAN, VPN ranges, or cloud-internal networks. Adjust the base ranges to fit your environment.
• The restart is disruptive. Restarting the daemon stops every running container, including workspaces. Plan it like any other host maintenance.

Checking usage

To see how close a host is to the limit, count its networks:

docker network ls | wc -l

Compare that against the pool capacity of your configuration. If you see a workspace fail with the message above while this count is high, the pools are the cause.