🐳
Docker Error
Docker Error: Port Is Already Allocated
A container failed to start because the host port you're trying to map is already in use by another process or container.
What This Error Means
This means `docker run -p HOST_PORT:CONTAINER_PORT` failed because something on the host machine — another container, or a regular process — is already bound to that host port, and two processes can't bind the same port simultaneously.
Why It Occurs
Most commonly, a previous container using the same port mapping was never properly stopped/removed, or an unrelated application on the host is already using that port.
Symptoms
- ⚠ `docker run` fails immediately with "port is already allocated" or "address already in use"
- ⚠ The specific host port mentioned is the one you tried to map
Common Causes
- • A previous container instance using the same port is still running (or stopped but not removed, in some Docker configurations)
- • A non-Docker process on the host is already listening on that port
- • Running the same docker-compose stack twice without stopping the first
How to Fix It
- Check what's using the port: `docker ps` to see if another container has it mapped, or `sudo ss -tulpn | grep :PORT` for any process on the host
- If it's an old container, stop and remove it: `docker stop container-id && docker rm container-id`
- If it's a non-Docker process legitimately using that port, either stop that process or map your container to a different host port instead: `-p 8081:80` instead of `-p 80:80`
- For docker-compose stacks, `docker-compose down` before `docker-compose up` again ensures old containers are properly removed first
| Command | Purpose |
|---|---|
| docker ps | List running containers and their port mappings |
| sudo ss -tulpn | grep :PORT | Check if a non-Docker process on the host holds the port |
| docker stop container-id && docker rm container-id | Stop and remove a conflicting container |
Advertisement
Verification
- ✓ `docker run` with the same port mapping now starts successfully
- ✓ `docker ps` shows the new container running with the expected port mapping
Prevention
- → Use `docker-compose down` (not just Ctrl+C) to cleanly stop and remove containers between runs
- → Use distinct host ports for different projects to avoid recurring collisions