Docker "port is already allocated" in CI

By Daniel Zoghalchali·Latchkey

Docker could not publish a container port because something already holds it on the host. In CI it is usually a leftover container from a previous step or a parallel job using the same port.

What this error means

A docker run or compose up fails with Bind for 0.0.0.0:5432 failed: port is already allocated. Freeing the port or stopping the other container lets it start.

docker: 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

Leftover container holding the port

A container from an earlier step was not removed and still publishes the port.

Parallel jobs sharing a host

Two jobs on the same runner both try to bind the same fixed host port.

A host process on the port

A non-Docker process is already listening on the chosen host port.

How to fix it

Free or change the port

1. Find and stop whatever holds the port, or pick a different host port.

docker ps --filter "publish=8080"
docker rm -f <container>

Avoid fixed host ports

1. Let Docker assign an ephemeral host port and read it back, or scope ports per job.

docker run -P app   # publish to random host ports
docker port <container>

How to prevent it

• Clean up containers between steps (docker rm -f), and avoid hardcoded host ports when jobs share a runner. This is a deterministic conflict, not transient.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation