Fix Docker "Port is Already Allocated" Error

The error

When Docker cannot bind to a port, you see one of these messages:

Error response from daemon: driver failed programming external connectivity:
Bind for 0.0.0.0:3000 failed: port is already allocated

Or in docker-compose:

ERROR: for web  Cannot start service web:
Ports are not available: listen tcp 0.0.0.0:8080: bind: address already in use

Quick fix: portrm

$ ptrm fix 3000
  Port 3000 in use
  node (PID 42187) - Express.js server
  Killed PID 42187. Port 3000 is free.

$ docker-compose up  # now it works

Cause 1: Another container using the port

An old or forgotten container is already bound to the port:

$ docker ps --filter "publish=3000"
CONTAINER ID  IMAGE        PORTS                   NAMES
a1b2c3d4e5    node:18      0.0.0.0:3000->3000/tcp  old-app

$ docker stop old-app
# Or remove it entirely
$ docker rm -f old-app

Cause 2: Host process using the port

A non-Docker process is bound to the port on the host system:

$ ptrm 3000
  Port 3000
  PID    21543
  Name   node
  Cmd    next-server

$ ptrm fix 3000  # kill it safely

Cause 3: docker-compose has duplicate ports

Two services in the same docker-compose.yml map to the same host port:

# docker-compose.yml (WRONG - both use 8080)
services:
  api:
    ports:
      - "8080:3000"
  admin:
    ports:
      - "8080:4000"   # conflict!

Fix by remapping one service to a different host port:

# docker-compose.yml (FIXED)
services:
  api:
    ports:
      - "8080:3000"
  admin:
    ports:
      - "8081:4000"   # no conflict

Cause 4: Stopped container still holding the port

Sometimes a container crashes but does not fully release its port binding:

$ docker ps -a --filter "status=exited" --filter "publish=3000"
$ docker rm $(docker ps -aq --filter "status=exited")

# Or nuclear option: remove all stopped containers
$ docker container prune

Prevent Docker port conflicts