EC
bind: address already in use
DockerERRORCriticalStartupHIGH confidence

Port is already allocated on the host

What this means

This error occurs when you try to map a container's port to a host port that is already being used by another container or a native process on the host. The Docker daemon cannot bind to the requested port because it's already occupied.

Why it happens
  1. 1Another Docker container is already running and mapped to the same host port.
  2. 2A local development server (e.g., Node.js, Python Flask) is running directly on the host using that port.
  3. 3A system service is occupying the port.
  4. 4You are trying to run multiple instances of the same service (e.g., in docker-compose) that all attempt to bind to the same static host port.
How to reproduce

You try to run a new Nginx container on port 8080, but an existing container is already using it.

trigger — this will error
trigger — this will error
# Start the first container, which successfully binds to port 8080
docker run -d -p 8080:80 --name web1 nginx
# Attempt to start a second container on the same host port
docker run -d -p 8080:80 --name web2 nginx

expected output

docker: Error response from daemon: driver failed programming external connectivity on endpoint web2 (...): Bind for 0.0.0.0:8080 failed: port is already allocated.

Fix 1

Stop the Conflicting Container or Process

WHEN The process using the port is no longer needed.

Stop the Conflicting Container or Process
# Find and stop the container using the port
docker ps
docker stop <conflicting_container_id>

# Or, find the process ID on the host (Linux/macOS)
sudo lsof -i -P -n | grep LISTEN
# Then kill the process
kill -9 <PID>

Why this works

This frees up the port on the host, allowing the new container to bind to it.

Fix 2

Use a Different Host Port

WHEN You need both services to run simultaneously.

Use a Different Host Port
# Map the new container's port 80 to host port 8081 instead
docker run -d -p 8081:80 --name web2 nginx

Why this works

This avoids the conflict by mapping the new container to a different, available port on the host machine.

Fix 3

Use a Dynamic Host Port

WHEN You don't care which host port is used, only that the container is accessible.

Use a Dynamic Host Port
# Let Docker choose a random, available port on the host
docker run -d -P --name web2 nginx
# Find out which port was assigned
docker port web2

Why this works

Using '-P' (uppercase) tells Docker to map all exposed ports to random high-numbered ports on the host, guaranteeing no conflicts.

What not to do

✕ Kill a process without knowing what it is.

The process occupying the port could be a critical system service. Blindly killing it could destabilize your operating system.

Sources
Official documentation ↗

Docker run reference

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Docker errors