How to fix Error starting userland proxy: listen tcp4 0.0.0.0:3000: bind: address already in use in Docker

DockerBEGINNERMEDIUMUpdated Dec 6, 2025· 136 views

The port you are trying to bind is already used by another process or container. Find and stop the conflicting process, or use a different port mapping.

Quick fix

Fixes EADDRINUSE

# On Linux/macOS
sudo lsof -i :3000

# Or using netstat
sudo netstat -tlnp | grep 3000

# On Windows
netstat -ano | findstr :3000
  1. Find what is using the port
  2. Check for running Docker containers
  3. Stop the conflicting container
  4. Stop the conflicting host process
docker — error
# On Linux/macOS
sudo lsof -i :3000
# Or using netstat
sudo netstat -tlnp | grep 3000
# On Windows
netstat -ano | findstr :3000
Error starting userland proxy: listen tcp4 0.0.0.0:3000: bind: address already in use

What this error means

This error occurs when Docker tries to bind a container port to a host port that is already in use. Each port on a host can only be bound by one process at a time. The "userland proxy" mentioned in the error is Docker port forwarding mechanism that listens on the host and forwards traffic to containers. When another process (or container) already occupies that port, Docker cannot start the proxy.

Typical symptoms

  • docker run fails immediately when specifying -p port mapping
  • docker-compose up fails for a specific service
  • Container starts but port forwarding fails
  • Error mentions a specific port number in the message
  • Same container works when port mapping is removed

Common causes

  1. Another container is already using that port
  2. A host service (nginx, apache, node) is binding the port
  3. A previous container instance is still running or in a zombie state
  4. Docker Compose service from a previous run was not stopped
  5. Host firewall or network service is using the port
  6. Another Docker Compose project uses the same port

How to fix "Error starting userland proxy: listen tcp4 0.0.0.0:3000: bind: address already in use"

1Find what is using the port

Identify the process currently binding the port:

bash
# On Linux/macOS
sudo lsof -i :3000

# Or using netstat
sudo netstat -tlnp | grep 3000

# On Windows
netstat -ano | findstr :3000

This shows the process ID (PID) and name using the port.

2Check for running Docker containers

See if another container is using the port:

bash
# List all containers (including stopped)
docker ps -a

# Check port mappings specifically
docker ps --format "table {{.Names}}	{{.Ports}}"

If you find a container using the port, stop or remove it.

3Stop the conflicting container

If another container is using the port:

bash
# Stop the container
docker stop <container_name_or_id>

# Or remove it entirely
docker rm -f <container_name_or_id>

For Docker Compose projects:

bash
docker-compose down
4Stop the conflicting host process

If a host process is using the port:

bash
# Stop by process name
sudo systemctl stop nginx  # or apache2, etc.

# Or kill by PID
sudo kill <PID>

# Force kill if necessary
sudo kill -9 <PID>

Consider whether you need that service running.

5Use a different port

If you cannot free the port, map to a different host port:

bash
# Change host port (first number), keep container port
docker run -p 3001:3000 myimage

# In docker-compose.yml
ports:
  - "3001:3000"

Update any application configuration to use the new port.

6Clean up zombie containers

Sometimes containers get stuck. Force cleanup:

bash
# Remove all stopped containers
docker container prune

# Restart Docker daemon (releases all ports)
sudo systemctl restart docker

Advanced notes

Docker Compose Port Conflicts: When running multiple Compose projects, use unique port mappings or define them via environment variables in your .env file.

Disable Userland Proxy: For better performance and to use iptables directly, add "userland-proxy": false to /etc/docker/daemon.json. Note: this may cause issues with some network configurations.

macOS/Windows: Check Docker Desktop port forwarding is not conflicting with host services. VPNs can sometimes cause port conflicts.

Frequently asked questions

What does "EADDRINUSE" mean?
This error occurs when Docker tries to bind a container port to a host port that is already in use. Each port on a host can only be bound by one process at a time. The "userland proxy" mentioned in the error is Docker port forwarding mechanism that listens on the host and forwards traffic to containers.
How do I fix "EADDRINUSE"?
The port you are trying to bind is already used by another process or container. Find and stop the conflicting process, or use a different port mapping.
What causes "EADDRINUSE"?
Another container is already using that port A host service (nginx, apache, node) is binding the port A previous container instance is still running or in a zombie state
Is the "EADDRINUSE" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading