Docker Port Allocation Failure

Docker cannot start a container because the specified host port (e.g., 80, 8080) is already in use by another process or container on the system.

Common Causes

Another Docker container is already running and listening on the same host port.
A non-Docker process (like a local web server) is using the requested port.
A previous container instance did not terminate cleanly, leaving the port in a 'TIME_WAIT' state.
The port is reserved by the host's operating system or firewall.

How to Fix

1 Identify and Stop the Conflicting Container

Find the container using the port and stop or remove it.

BASH

 $ # List all running containers and their ports
docker ps
# Stop the container using the port (replace <container_id>)
docker stop <container_id>
# Or, remove it if it's no longer needed
docker rm <container_id>

2 Find and Kill the Non-Docker Process

Use system commands to identify the process holding the port and terminate it.

BASH

 $ # On Linux/macOS, find the PID using the port (e.g., port 8080)
lsof -i :8080
# Or use netstat
netstat -tulpn | grep :8080
# Kill the process using its PID
kill -9 <PID>

3 Change the Container's Host Port Binding

Modify your `docker run` command or compose file to map the container port to a different, free host port.

BASH

 $ # Instead of -p 8080:80, use a different host port like 8081
docker run -p 8081:80 nginx
# In docker-compose.yml, change the ports mapping
# ports:
#   - "8081:80"

4 Use a Dynamic Host Port

Let Docker assign a random free host port by omitting the first part of the `-p` flag.

BASH

 $ docker run -p :80 nginx
# Docker will output the assigned port, e.g., 0.0.0.0:32768->80/tcp