Docker "driver failed programming external connectivity" in CI

Docker could not set up the host-to-container port mapping. The networking driver failed to program the port forward - usually because the host port is already in use or a stale rule is in the way.

What this error means

A docker run -p or docker compose up fails to start a container with driver failed programming external connectivity on endpoint ... bind ... address already in use (or a similar netlink/iptables error).

docker run output

Error response from daemon: driver failed programming external connectivity
on endpoint web (...): Bind for 0.0.0.0:8080 failed: port is already allocated

Common causes

The host port is already bound

Another process or a leftover container is already listening on the host port you are mapping, so the driver cannot bind it again.

Stale iptables/netfilter rules

A previous container that did not clean up can leave dangling NAT rules, so programming the new mapping fails even though nothing is obviously listening.

The userland proxy / firewall conflict

A host firewall or a conflicting docker-proxy from a prior run can block the new port-forward setup.

How to fix it

Find and free the conflicting port

Identify what holds the port, then stop it or pick another host port.

Terminal

ss -ltnp | grep ':8080'      # what is on the port?
docker ps --filter "publish=8080"
docker rm -f <leftover-container> || true

Reset Docker networking state if rules are stale

Remove leftover containers and prune unused networks.
Restart the Docker daemon to reprogram iptables cleanly if rules are dangling.
Map to a different, known-free host port as a quick unblock.

How to prevent it

Use --rm and cleanup steps so containers release ports on exit.
Avoid hardcoding host ports that other jobs on the runner may use.
Prune unused networks on long-lived runners between jobs.