Docker "driver failed programming external connectivity" (Port) in CI

The daemon could not publish a container port to the host. driver failed programming external connectivity on endpoint ... is usually bind: address already in use - the host port is taken - or an iptables rule the daemon could not program.

What this error means

A docker run -p 8080:8080 ... fails with Error response from daemon: driver failed programming external connectivity on endpoint <name>: ... bind: address already in use (or an iptables error). Choosing a free host port works.

docker

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

Common causes

The host port is already in use

Another container or a host process already bound the published port, so the new bind fails with address already in use.

A leftover container still holds the port

A previous container from the same job that was not removed keeps the host port mapped on a persistent runner.

iptables rule could not be programmed

If the daemon cannot program the NAT/forwarding rule (iptables disabled or broken), publishing the port fails here too.

How to fix it

Free the port or pick a different one

Stop whatever holds the port, or publish to a free host port.

Terminal

# find and remove the holder:
docker ps --filter publish=8080
docker rm -f $(docker ps -q --filter publish=8080) 2>/dev/null || true
# or use an ephemeral host port:
docker run -p 0:8080 myorg/api:1.4.2

Use unique ports per job and clean up

Avoid fixed host ports across concurrent jobs and remove containers after use.