Why Does Docker Fail to Start? Diagnose and Fix Network Subnet Conflicts

1 Pre‑knowledge

Because switch capacity is limited and Ethernet cables cannot be infinitely long, you cannot connect all hosts to a single switch in one Layer‑2 network; ARP broadcasts would also cripple the network.

Therefore hosts must be split into smaller subnets and linked via routers to form a Layer‑3 network.

An IP address consists of a network part and a host part, e.g., 10.0.0.1/8 where 10 is the network address and 0.0.1 is the host address. The subnet mask (the /8) tells you how to separate the two.

IP addresses are 32‑bit binary numbers written in dotted decimal for readability. A simple rule: each octet is 8 bits, so /8 means the first octet is the network, /16 means the first two octets are the network, etc.

For example, 10.0.0.1/16 and 10.0.0.2/16 belong to the same subnet, while 10.0.0.1/16 and 10.1.0.1/16 are in different subnets.

2 Symptom

Docker daemon fails to start.

Container ports are unreachable; inbound traffic appears but no outbound traffic.

3 Troubleshooting

This section focuses on dockerd failing to start; if dockerd can start, skip to the solution.

First check the logs:

$ systemctl status docker<br/>$ journalctl -u docker<br/>$ dmesg | grep docker

Typical log entries:

docker0: link is not ready<br/>docker_gwbridge: link is not ready

Alternatively, try to start dockerd manually and inspect the ExecStart line in /usr/lib/systemd/system/docker.service: $ /usr/bin/dockerd --debug If the output ends with an error like:

failed to start daemon: Error initializing network controller: list bridge addresses failed: PredefinedLocalScopeDefaultNetworks List: [10.252.0.0/24 10.252.1.0/24 10.252.2.0/24]: no available network

Check the current interfaces with ip addr. If docker0 or docker_gwbridge are missing, the failure is likely due to Docker being unable to create those bridges.

4 Solution

Find the conflicting subnet

The default Docker bridge network is 172.17.0.0/16 and the default docker_gwbridge is 172.18.0.0/24. Ping these ranges or inspect the routing table with route -n to see if they are already in use.

Example conflict:

10.0.0.0        172.21.0.1      255.0.0.0       UG      0      0        0 eth0

Here the 10/8 network is already routed, causing a clash with a custom 10.252.0.0/24 Docker bridge.

Modify Docker’s occupied subnets

Stop Docker first: $ systemctl stop docker Docker can occupy four networks: docker0, docker_gwbridge, ucp (rare), and ingress. The first three can be configured via /etc/docker/daemon.json (create the file if it does not exist):

{
  "bip": "",
  "default-address-pools": [
    {"base": "10.252.0.0/24", "size": 24},
    {"base": "10.252.1.0/24", "size": 24},
    {"base": "10.252.2.0/24", "size": 24}
  ]
}

The default-address-pools array must contain at least two entries for docker0 and docker_gwbridge; adding a third for ucp is advisable.

Adjust the ingress network

After initializing a Docker Swarm, delete the default ingress network and recreate it with a non‑conflicting subnet:

$ yes 'y' | docker network rm ingress
$ yes 'y' | docker network rm my-ingress 2>&1 | true
$ docker network create \
  --driver overlay \
  --ingress \
  --subnet=10.252.3.0/24 \
  --gateway=10.252.3.2 \
  --opt com.docker.network.driver.mtu=1200 \
  my-ingress

Because removal of the ingress network is asynchronous, use a different name (e.g., my‑ingress) to avoid name‑collision errors.

Before restarting Docker, clean up old network artifacts:

$ ip link del dev docker0
$ ip link del dev docker_gwbridge
$ rm -rf /var/lib/docker/network

Quick but temporary fix

You can manually create a docker0 bridge:

ip link add name docker0 type bridge
ip addr add dev docker0 10.252.0.1/24

This restores Docker startup but the bridge disappears after a reboot and does not resolve underlying subnet conflicts.

Source: https://tinyurl.com/4era6brf