🚨 Docker Error Guide: 'failed to set up container networking' Bridge and IP Allocation Failures

Exact Error Message

failed to set up container networking appears when docker run or docker start reaches the point of attaching a container to a network and the daemon cannot complete the wiring:

docker: Error response from daemon: failed to set up container networking:
driver failed programming external connectivity on endpoint zealous_morse
(a1b2c3...): Error starting userland proxy: listen tcp4 0.0.0.0:8080:
bind: address already in use.

Error response from daemon: failed to set up container networking:
failed to allocate gateway (172.17.0.1): Address already in use

Error response from daemon: failed to set up container networking:
could not find an available, non-overlapping IPv4 address pool among
the defaults to assign to the network.

The container image is fine and the process never starts; the failure is purely in attaching the container’s network endpoint to a Docker network.

What the Error Means

When a container starts, Docker’s network driver (usually bridge) must assign the container an IP from the network’s subnet, create a veth pair, plug it into the bridge (docker0 for the default network), and program iptables/nftables NAT and forwarding rules for any published ports. “Set up container networking” is this whole sequence. If any step fails — no free IP in the pool, the bridge is missing or misconfigured, a published port collides, or firewall rules cannot be written — the daemon aborts the start and reports this wrapper error.

The exact cause is in the text after the colon. address already in use points at a port or gateway collision; non-overlapping IPv4 address pool means Docker ran out of subnets to allocate; iptables failures point at firewall or kernel-module problems. Treat the suffix as the real error and the wrapper as context.

Common Causes

• Exhausted IP address pool. Too many user-defined networks have consumed all default /16 and /20 pools, so no non-overlapping subnet remains.
• Published port already in use. Another process (or another container) already holds the host port, so the userland proxy cannot bind.
• Damaged or missing docker0 bridge. The default bridge was deleted, renamed, or left in a bad state by a crash or by NetworkManager.
• iptables/nftables problems. The firewall backend is disabled, the legacy/nft mismatch breaks rule insertion, or a custom firewall flushed Docker’s chains.
• Stale network state. A previous unclean shutdown left endpoints or sandboxes referencing IPs that are no longer free.
• Conflicting host routes/subnets. A VPN or corporate subnet overlaps Docker’s default ranges, so allocation is refused.

How to Reproduce the Error

Create enough custom networks to exhaust the default address pools, then add one more:

for i in $(seq 1 40); do docker network create net$i >/dev/null 2>&1; done
docker run --rm --network bridge alpine true

Error response from daemon: failed to set up container networking:
could not find an available, non-overlapping IPv4 address pool among
the defaults to assign to the network.

Remove the test networks afterward with docker network rm net1 ... net40.

Diagnostic Commands

List networks and inspect their subnets to spot pool exhaustion:

docker network ls
docker network inspect bridge | grep -i 'subnet\|gateway\|address'

Confirm the default bridge exists and is up on the host:

ip -br addr show docker0
ip route | grep docker0

Check whether the published host port is already bound:

ss -ltnp | grep ':8080'

Read the daemon log for the precise driver failure and look at iptables state:

journalctl -u docker --since "10 min ago" | grep -i 'network\|iptables\|bridge\|allocate'
iptables -t nat -L DOCKER -n

Step-by-Step Resolution

Cause: exhausted IP pool. Remove unused networks so subnets are freed, then retry:

docker network prune -f
docker network ls

If you genuinely need many networks, configure additional/larger default-address-pools in /etc/docker/daemon.json and restart the daemon.

Cause: published port in use. Identify the holder and either stop it or publish on a different host port:

ss -ltnp | grep ':8080'
docker run -p 8081:80 nginx

Cause: damaged docker0 bridge. Restarting the daemon recreates the default bridge cleanly:

systemctl restart docker
ip -br addr show docker0

If a tool keeps deleting docker0, exclude it (for example tell NetworkManager to ignore Docker interfaces).

Cause: iptables/nftables. Ensure the firewall backend matches what Docker expects and that the daemon can write its chains. After fixing the backend, restart Docker so it re-inserts the DOCKER chains:

journalctl -u docker | grep -i iptables
systemctl restart docker

If a host firewall flushes rules on reload, configure it to preserve or re-add Docker’s chains.

Cause: stale network state. Disconnect and reconnect, or restart the daemon to clear orphaned endpoints. As a last resort, recreate the offending user-defined network.

A worked example. A CI runner suddenly fails every docker run with could not find an available, non-overlapping IPv4 address pool. docker network ls shows over thirty leftover per-build networks that the pipeline never tore down. docker network prune -f removes the unused ones, freeing their subnets, and containers start immediately. The fix is also preventive: the pipeline now removes its compose networks in a cleanup step.

Prevention and Best Practices

• Run docker network prune (or tear down compose networks per job) so per-build networks cannot exhaust the address pools.
• Size default-address-pools in daemon.json to match how many networks you actually need.
• Pick host ports deliberately and check ss -ltnp before publishing to avoid collisions.
• Keep one firewall backend consistent (don’t mix iptables-legacy and nftables) and let Docker manage its own chains.
• Avoid overlapping Docker’s default subnets with VPN/corporate ranges; reassign pools if they collide.

Related Errors

• Docker Error Guide: ‘port is already allocated’ — the port-collision variant of this networking failure.
• Docker Error Guide: ‘error initializing network controller’ — daemon-level networking startup failure.
• See more Docker troubleshooting guides.

Frequently Asked Questions

Why does this happen only sometimes? Intermittent failures usually mean IP-pool or port exhaustion that depends on how many containers/networks already exist. The same command works once a network is pruned or a port is freed.

Does restarting Docker fix it? It fixes bridge corruption and stale endpoint state, but it will not help exhausted pools or a genuinely occupied host port — those need pruning or a different port.

Can I just use host networking to avoid this? --network host skips bridge setup but removes isolation and port mapping. It is a workaround for specific cases, not a general fix for pool or firewall problems.

Is this a registry or image problem? No. The image already downloaded and validated; this error is entirely about attaching the container to a network on the host.