Docker "port is already allocated" / "address already in use" in CI

Docker tried to publish a container port to a host port that is already taken - by another container, a leftover from a previous job, or a service on the runner.

What this error means

A docker run -p or docker compose up fails with Bind for 0.0.0.0:<port> failed: port is already allocated. On a fresh runner it is often a leftover container from an earlier step.

docker run output

Error response from daemon: driver failed programming external connectivity on
endpoint db: Bind for 0.0.0.0:5432 failed: port is already allocated

Common causes

A previous container still holds the port

An earlier step started a container mapping the same host port and did not stop it, so the new run collides.

Another process on the runner uses the port

A service preinstalled on the runner (a database, a previous job’s daemon) is already bound to that host port.

Parallel jobs sharing a host

On a shared/self-hosted runner, two concurrent jobs both try to publish the same fixed host port.

How to fix it

Stop leftover containers first

Clean up containers that may be holding the port at the start of the job.

Terminal

docker ps --filter "publish=5432" -q | xargs -r docker rm -f
# or full reset in CI:
docker compose down --remove-orphans

Use an ephemeral host port or internal networking

Let Docker pick a random host port (-p 5432 → -p ::5432) or omit the host side and use the container network.
In compose, have services talk over the compose network instead of publishing ports.
Avoid fixed host ports for concurrent jobs on shared runners.

How to prevent it

Tear down containers (docker compose down) at job start and end.
Prefer internal networking over publishing fixed host ports in CI.
Avoid hard-coded host ports when jobs may run concurrently.