Fix: Docker Error: Bind for 0.0.0.0:PORT failed: port is already allocated

The Error

You start a Docker container and get:

docker: Error response from daemon: driver failed programming external connectivity on endpoint mycontainer:
Bind for 0.0.0.0:3000 failed: port is already allocated.

Or with Docker Compose:

Error starting userland proxy: listen tcp4 0.0.0.0:5432: bind: address already in use

The container refuses to start. Something else is already listening on the port you’re trying to bind.

Why This Happens

Docker maps container ports to host ports using -p or ports in Docker Compose. When you run -p 3000:3000, Docker tells the host OS to forward traffic from host port 3000 to container port 3000. If something else is already using host port 3000, the bind fails.

Common causes:

• Another container is using the port. A previous container is still running or in a stopped state with the port allocated.
• A host process is using the port. A local development server (Node.js, Python, etc.) is running on the same port.
• Docker Compose services conflict. Two services in the same Compose file map to the same host port.
• A previous container did not shut down cleanly. Docker’s proxy process still holds the port.
• Docker Desktop reserved the port. On macOS and Windows, Docker Desktop’s networking layer can hold ports after containers stop.

Fix 1: Find What Is Using the Port

First, identify what is occupying the port.

Linux:

sudo lsof -i :3000

Or:

sudo ss -tlnp | grep 3000

macOS:

lsof -i :3000

Windows (PowerShell):

netstat -ano | findstr :3000

The output shows the process ID (PID) using the port. If it is a Docker container, you will see docker-proxy or com.docker. If it is another application, you will see its process name.

If the port conflict is with a non-Docker process, see Fix: Port 3000 already in use for a comprehensive guide on freeing ports.

Fix 2: Stop or Remove the Conflicting Container

If another Docker container is using the port, find and stop it:

docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Ports}}"

Look for a container bound to the same port. Stop it:

docker stop <container-id>

If the container is stopped but still holding the port (rare but possible):

docker rm <container-id>

To see all containers, including stopped ones:

docker ps -a

Remove all stopped containers at once:

docker container prune

Pro Tip: Use docker ps -q --filter "publish=3000" to find containers bound to a specific port directly. This is faster than scanning the full docker ps output when you have many containers.

Fix 3: Change the Host Port Mapping

If you cannot stop what is using the port, map your container to a different host port:

# Instead of -p 3000:3000, use a different host port
docker run -p 3001:3000 myapp

This maps host port 3001 to container port 3000. Your app inside the container still listens on 3000, but you access it at localhost:3001 from the host.

In Docker Compose:

services:
  web:
    image: myapp
    ports:
      - "3001:3000"  # host:container

Fix 4: Fix Docker Compose Port Conflicts

Two services in the same Compose file cannot share the same host port:

# BROKEN — both services try to bind host port 5432
services:
  db1:
    image: postgres:16
    ports:
      - "5432:5432"
  db2:
    image: postgres:16
    ports:
      - "5432:5432"  # Conflict!

Fix: Use different host ports:

services:
  db1:
    image: postgres:16
    ports:
      - "5432:5432"
  db2:
    image: postgres:16
    ports:
      - "5433:5432"  # Different host port

If services only need to communicate with each other (not with the host), remove the ports mapping entirely and use Docker’s internal networking:

services:
  web:
    image: myapp
    depends_on:
      - db
  db:
    image: postgres:16
    # No ports mapping — only accessible from other containers via 'db:5432'

Containers on the same Docker Compose network can reach each other by service name without exposing ports to the host.

Fix 5: Kill the Process Using the Port

If the port is held by a non-Docker process, kill it:

Linux/macOS:

# Find the PID
lsof -ti :3000

# Kill it
kill $(lsof -ti :3000)

# Force kill if it doesn't stop
kill -9 $(lsof -ti :3000)

Windows (PowerShell):

$pid = (Get-NetTCPConnection -LocalPort 3000).OwningProcess
Stop-Process -Id $pid -Force

Then start your Docker container again.

Common Mistake: Killing docker-proxy directly. If lsof shows docker-proxy on the port, do not kill it manually — stop the container that owns it with docker stop. Killing the proxy process directly can leave Docker’s networking in a bad state.

Fix 6: Restart Docker

If the port is held by a ghost Docker process that won’t release, restarting Docker often fixes it.

Docker Desktop (macOS/Windows):

Quit Docker Desktop and reopen it. Or use the menu: Docker icon → Restart.

Linux:

sudo systemctl restart docker

After restarting, try starting your container again. All containers will stop during the restart, so make sure that is acceptable.

If Docker itself won’t start after the restart, see Fix: Docker daemon is not running.

Fix 7: Use Docker’s Random Port Assignment

If you don’t care which host port is used, let Docker pick one:

docker run -p 3000 myapp

Notice the single port — no host port specified. Docker assigns a random available host port. Find it with:

docker port <container-id>

Output:

3000/tcp -> 0.0.0.0:49153

In Docker Compose:

services:
  web:
    image: myapp
    ports:
      - "3000"  # Random host port

This is useful for development and testing when the exact port doesn’t matter.

Fix 8: Clean Up Docker Resources

Accumulated stopped containers, unused networks, and dangling images can sometimes interfere with port allocation:

docker system prune

For a more thorough cleanup:

docker system prune -a --volumes

Warning: The -a --volumes flags remove all unused images and volumes. This includes data volumes, which may contain database data. Use with caution. If Docker is running low on disk space, see Fix: Docker no space left on device.

Fix 9: Check for Host Networking Mode Issues

If you use --network host (Linux only), the container shares the host’s network namespace. The container’s ports are directly exposed on the host without mapping:

docker run --network host myapp

If the app inside the container listens on port 3000, it directly binds to host port 3000. This bypasses Docker’s port mapping entirely and conflicts with anything else on port 3000.

Fix: Either stop the conflicting process, change the app’s listening port, or switch back to bridge networking with port mapping.

Host networking is not available on Docker Desktop (macOS/Windows) — it only works on Linux. If you’re having Docker permission issues on Linux, check Fix: Docker permission denied socket.

Still Not Working?

If the port conflict persists after trying everything above:

Check for IPv6 conflicts. A process might be bound to [::]:3000 (IPv6) while Docker tries 0.0.0.0:3000 (IPv4). Check both:

sudo ss -tlnp | grep 3000

Check for ports reserved by the OS. Windows reserves certain port ranges for Hyper-V and WSL. Check reserved ranges:

netsh interface ipv4 show excludedportrange protocol=tcp

If your port falls in an excluded range, choose a different port.

Check Docker Desktop settings. On macOS and Windows, Docker Desktop has its own networking layer. Restarting Docker Desktop often releases stuck ports when docker restart alone does not.

Check for docker-compose vs docker compose. If you have both the old docker-compose (Python-based) and the new docker compose (Go plugin) installed, they manage containers separately. A container started with one won’t be visible to the other. Standardize on docker compose (the plugin).

Use docker network inspect to debug networking:

docker network inspect bridge

This shows all containers on the bridge network and their port bindings. If you see ERR_CONNECTION_REFUSED when trying to connect to your container, the issue might be in the container’s configuration rather than port allocation.