6.3.2.5 Port Collision Handling

Port collision handling addresses what happens when attempting to publish a host port that is already in use by another container or process, requiring either freeing the conflicting port, choosing a different host port, or letting Docker assign one automatically.

Recognizing a Port Collision

Attempting to bind an already-used host port produces a clear error at container startup, rather than silently failing.

docker run -d -p 8080:80 app-a:1.0
docker run -d -p 8080:80 app-b:1.0

Error response from daemon: Bind for 0.0.0.0:8080 failed: port is already allocated

Identifying What's Using the Conflicting Port

Determining what is currently using a given host port helps decide the best way to resolve the collision.

docker ps --filter "publish=8080"

This reveals which running container, if any, is currently bound to port 8080.

Resolving the Collision by Choosing a Different Port

The simplest resolution is often to choose an alternative, currently unused host port for the new container.

docker run -d -p 8081:80 app-b:1.0

Resolving the Collision by Letting Docker Assign a Port Automatically

Rather than manually finding an available port, Docker can be left to choose one automatically.

docker run -d -p 80 app-b:1.0
docker port $(docker ps -lq)

Resolving the Collision by Stopping the Conflicting Container

If the existing container using the port is no longer needed, stopping or removing it frees the port for the new container to use instead.

docker stop app-a
docker run -d -p 8080:80 app-b:1.0

Why Port Collision Handling Matters

Understanding how to identify and resolve port collisions is a routine, practical skill needed whenever multiple containers (or other processes) compete for limited host-level port availability, particularly common in local development environments running several services simultaneously.