Fix: Docker Compose Port Already in Use

!Symptoms

• docker compose up fails with 'port is already allocated'
• Container starts but immediately exits
• Address already in use error on specific ports
• Only some services in the compose file fail to start

?Root Causes

• Another container or host process already using the same port
• Previous docker compose session not properly stopped
• Multiple compose files mapping to the same host port
• Host service (nginx, postgresql, redis) bound to the same port
• Docker network remnants from a previous run

#Diagnosis Steps

1. 1Check what's using the port: `lsof -i :<port>` or `ss -tlnp | grep <port>`
2. 2List running containers: `docker ps` and `docker compose ps`
3. 3Check for orphaned containers: `docker ps -a --filter status=exited`
4. 4List all docker networks: `docker network ls`
5. 5Check host services: `systemctl list-units --type=service --state=running`

>Fix

1. 1Stop the conflicting process: `kill <pid>` or `systemctl stop <service>`
2. 2Stop previous compose: `docker compose down` in the project directory
3. 3Change the host port in docker-compose.yml: `8081:80` instead of `80:80`
4. 4Remove orphaned containers: `docker compose down --remove-orphans`
5. 5Prune unused networks: `docker network prune`

*Prevention

• Use unique port ranges per project in docker-compose.yml
• Always run `docker compose down` before starting a new session
• Use `.env` files to make ports configurable per developer
• Document which ports each project uses in the README
• Use Docker's random port assignment for development: `ports: ['80']` without host port

Related Error Messages