Docker Port Is Already Allocated: Find the Process Using a Port

Docker reports port is already allocated when a host port in your Compose mapping is already owned by another container or process. Identify the owner first, then stop it only when you know it is no longer needed.

Read the port mapping correctly

In this mapping, 8080 is the host port and 3000 is the container port:

services:
  api:
    ports:
      - "8080:3000"

The conflict is on 8080, not necessarily on port 3000 inside the container.

Check Docker containers first

docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Ports}}"
docker ps -a --filter publish=8080
docker compose ls

If an old project owns the port, stop that project deliberately:

docker compose -p old-project down

Do not run a broad docker compose down from an unrelated directory.

Find a host process on Linux

sudo ss -ltnp 'sport = :8080'
sudo lsof -nP -iTCP:8080 -sTCP:LISTEN

Inspect the service before stopping it:

ps -fp <PID>
sudo systemctl status <service-name>

Find a host process on Windows

Get-NetTCPConnection -LocalPort 8080 -State Listen
Get-Process -Id <PID>

The legacy alternative is:

netstat -ano | findstr :8080
tasklist /FI "PID eq <PID>"

Only terminate a process after confirming what it belongs to.

Change the host port when both services are needed

services:
  api:
    ports:
      - "8081:3000"

You can then open http://localhost:8081 while the application still listens on port 3000 inside its container.

Avoid unnecessary port publishing

If only another Compose service needs the API, remove ports and use the private network:

services:
  api:
    expose:
      - "3000"

The reverse proxy can reach the service by its Compose name, such as api:3000.

Common causes

• A previous Compose project was left running.
• A local Node.js, Nginx, IIS, or database process uses the port.
• Two services publish the same host port.
• A development tool and Docker both use port 3000 or 8080.
• A restarting container immediately reclaims the port.

Five-minute checklist

1. Read the host side of the mapping.
2. Run docker ps and find published ports.
3. Check the operating system’s listening processes.
4. Inspect the owner before stopping anything.
5. Stop the correct project or choose another host port.
6. Run docker compose up -d and verify with docker compose ps.

This is a resource ownership problem, not an instruction to kill every process that looks related to Docker.