7.3.1.5 Allocated Port Conflict

An allocated port conflict occurs when attempting to publish a host port already in use by another container or host process, resulting in a clear startup error rather than a silent failure, making this particular cause among the easiest to diagnose.

Recognizing This Specific Error

Attempting to start a container with a conflicting port mapping produces an immediate, explicit error at startup.

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 Currently Using the Conflicting Port

Determining exactly what is currently bound to the conflicting port informs the best way to resolve it.

docker ps --filter "publish=8080"
sudo ss -tlnp | grep 8080

The first command reveals a conflicting Docker container; the second reveals any conflicting process at the host level entirely outside of Docker.

Resolving by Choosing a Different Host Port

The most straightforward resolution simply avoids the conflict by selecting an available alternative host port.

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

Resolving by Stopping the Conflicting Container

If the existing container using the port is no longer needed, removing it frees the port for the new container.

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

Why This Particular Cause Is Relatively Easy to Diagnose

Unlike several other port-related issues that fail silently (leaving a container appearing to run normally while remaining unreachable), a port allocation conflict produces an immediate, explicit error specifically identifying the conflicting port — making this comparatively the most straightforward port-related problem to recognize and resolve.

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

Letting Docker assign an available port automatically sidesteps the need to manually find one in cases where the specific host port number doesn't actually matter.