When running a Docker container with port mapping, you might encounter:
Error starting userland proxy: listen tcp 0.0.0.0:8080: bind: address already in use
This means another process is already using the port you’re trying to map on your host machine.
1️⃣ Why This Happens
When you run:
docker run -p 8080:80 my_image
Docker tries to bind your host’s port 8080 to the container’s port 80.
If port 8080 is already in use by:
- Another Docker container
- A local application (e.g., Node.js, Apache, Nginx, PostgreSQL)
- A background service
Docker cannot start the new container, resulting in this error.
2️⃣ How to Find Which Process Is Using the Port
Linux / macOS
lsof -i :8080
or
sudo netstat -tulpn | grep :8080
Windows (PowerShell)
netstat -ano | findstr :8080
Once you have the PID, check which process it belongs to:
tasklist /FI "PID eq <PID>"
3️⃣ How to Fix
Option 1 — Stop the Process Using the Port
If it’s a container:
docker ps
docker stop <container_id>
If it’s a local application:
- Stop it manually
- Or kill it:
kill -9 <PID>
Option 2 — Use a Different Port
If 8080 is busy, run:
docker run -p 8081:80 my_image
This binds host port 8081 to the container’s port 80.
Option 3 — Remove Stale Docker Containers
Sometimes stopped containers still reserve the port due to leftover networking.
Remove unused containers:
docker ps -a
docker rm <container_id>
4️⃣ Tips to Avoid This Error
- Use
docker psregularly to see which ports are in use. - Keep a port mapping list for your services.
- When testing, use high-numbered ports (e.g., 5000–9000) to reduce conflicts.
📌 Summary
- Cause: Another process (Docker or otherwise) is using the port.
- Fix: Stop the process, choose another port, or remove old containers.
- Command to check:
- Linux/macOS:
lsof -i :<port> - Windows:
netstat -ano | findstr :<port>
- Linux/macOS: