We earn commissions when you shop through the links below, at no extra cost to you. Our guides and technical recommendations are written independently of these relationships: a commission never decides what we recommend, how we diagnose a problem or what we publish, and the content does not depend on it. Affiliate disclosure

Docker · Beginner · 10 min

Fix 'port is already allocated' in Docker

Fix Docker "port is already allocated": find who holds the host port, remove the half-created container, and publish on a free port.

Only one listener can own a host port. This runbook reads the two error messages Docker 29 prints, finds the container or host process that holds the port, removes the container the failed run left behind, and picks a fix. Commands were run on Ubuntu 26.04 with Docker Engine 29.1.3.

See it run

A short replay of real output from commands in this guide, captured on a WSL2 Ubuntu test machine (Docker 29.1.3, run as root so ss can name the owning process). The typing is replayed, and the host name, account and MAC addresses are redacted. Your output will differ, and a test machine is not a production server.

Text version of this demo
ops@web-01:~$ docker run -d --name ob-port-b -p 8080:80 nginx:1.27-alpine; echo "exit=$?"
06907999fb2193b9849f891677b375202816c43c55e2ffa672437f5a0c1e4026
docker: Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint ob-port-b (0774d87d06769b775c0ddc0881b65c420a674364b21261c919c9a5c9ec605068): Bind for 0.0.0.0:8080 failed: port is already allocated

Run 'docker run --help' for more information
exit=125

ops@web-01:~$ docker ps --filter publish=8080 --format 'table {{.Names}}\t{{.Image}}\t{{.Ports}}'
NAMES       IMAGE               PORTS
ob-port-a   nginx:1.27-alpine   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

ops@web-01:~$ sudo ss -ltnp 'sport = :8080'
State   Recv-Q  Send-Q    Local Address:Port     Peer Address:Port  Process                                   
LISTEN  0       4096            0.0.0.0:8080          0.0.0.0:*      users:(("docker-proxy",pid=37068,fd=7))  
LISTEN  0       4096               [::]:8080             [::]:*      users:(("docker-proxy",pid=37076,fd=7))  

ops@web-01:~$ docker ps -a --filter name=ob-port --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
NAMES       STATUS        PORTS
ob-port-b   Created       
ob-port-a   Up 1 second   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

ops@web-01:~$ docker rm ob-port-b && docker run -d --name ob-port-b -p 8081:80 nginx:1.27-alpine >/dev/null && docker port ob-port-b
ob-port-b
80/tcp -> 0.0.0.0:8081
80/tcp -> [::]:8081

ops@web-01:~$ curl -s -o /dev/null -w 'http %{http_code}\n' http://127.0.0.1:8081/
http 200

docker run -p 8080:80 asks Docker to listen on port 8080 of the host and forward it to port 80 in the container. Only one listener can own a host port. When something already holds it, the container is created but never starts, and docker run exits with code 125. This runbook finds who holds the port, removes the half-created container, and picks a fix that does not break whatever was there first.

Commands and output were captured on an Ubuntu 26.04 test machine with Docker Engine 29.1.3. Messages differ slightly between Docker versions; the cause is the same.

0. Rules of engagement

  1. Find the owner before you stop anything. The port may belong to a production container or a host service someone else depends on.
  2. Change the host side only. The container port (the number after the colon) is what the application listens on inside the container. It rarely needs to change.
  3. Do not reach for docker system prune. The leftover container from the failed run is one specific container; remove that one.

1. Read the error

Who holds the port decides the messageport is already allocated: docker run -p 8080:80 (asks the daemon to publish 8080) then Another container publishes 8080 (the same Docker daemon) then Find it with docker ps (stop it, or publish another port) address already in use: docker run -p 8080:80 (asks the daemon to publish 8080) then A host process listens on 8080 (web server, dev server, a second Docker daemon) then Find it with ss (stop it, or publish another port)port is already allocateddocker run -p 8080:80asks the daemon to publish 8080Another containerpublishes 8080the same Docker daemonFind it with docker psstop it, or publish anotherportaddress already in usedocker run -p 8080:80asks the daemon to publish 8080A host process listenson 8080web server, dev server, asecond Docker daemonFind it with ssstop it, or publish anotherport
Docker ends the message differently when another container holds the port and when a host process does. The ending tells you which command to run.

Docker 29 reports the two cases with different messages:

# Another container already publishes the port
docker: Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint ob-port-b (0774d87d...): Bind for 0.0.0.0:8080 failed: port is already allocated

The address in Bind for ... can also read :::8080, the IPv6 listener; it depends on which listener Docker tried first. Both runs on the test machine showed one of each.

# A process on the host (not a container) already listens on the port
docker: Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint ob-web3 (499ef852...): failed to bind host port 0.0.0.0:8081/tcp: address already in use
Message ends withWho holds the portGo to
port is already allocatedAnother container published by this Docker daemonSection 2.1
address already in useA process on the host: a web server, a dev server, a second Docker daemonSection 2.2
forbidden by its access permissions (Docker Desktop on Windows)A port range reserved by WindowsSection 5

Both failures exit with code 125: the daemon could not run the container. The container itself was created and stays in the Created state (section 3).

2. Find who holds the port

2.1 Another container

# Running containers that publish host port 8080
docker ps --filter publish=8080 --format 'table {{.Names}}\t{{.Image}}\t{{.Ports}}'
# Real output from the test machine
NAMES       IMAGE               PORTS
ob-port-a   nginx:1.27-alpine   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

With Compose, the owner is often a service from another project that is still running:

# All Compose projects on this host, including ones started from other folders
docker compose ls

2.2 A process on the host

ss shows the process name only for sockets you own, so use sudo:

# Listener on TCP port 8080 with the owning process
sudo ss -ltnp 'sport = :8080'
# Real output from the test machine: the owner here is Docker's own port proxy
State   Recv-Q  Send-Q    Local Address:Port     Peer Address:Port  Process
LISTEN  0       4096            0.0.0.0:8080          0.0.0.0:*      users:(("docker-proxy",pid=37068,fd=7))
LISTEN  0       4096               [::]:8080             [::]:*      users:(("docker-proxy",pid=37076,fd=7))
  • docker-proxy means a container of this daemon publishes the port. Go back to section 2.1.
  • Any other name (nginx, node, python3, java) is a host process. Decide with its owner whether it should run.
  • No listener at all, but Docker still says the port is allocated: another Docker context or daemon, or a container from a Compose project you did not check. Run docker context ls and docker ps -a again.

3. Remove the half-created container

With -d, docker run first prints the new container's ID, then the error: the container was created, but its networking could not be set up. It stays in the Created state. It holds the name, so the next docker run --name with the same name fails with a name conflict.

# Containers whose name starts with ob-port, with state and ports
docker ps -a --filter name=ob-port --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
# Real output from the test machine
NAMES       STATUS        PORTS
ob-port-b   Created
ob-port-a   Up 1 second   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp
# Remove only the container that never started
docker rm ob-port-b

4. Fix

Pick one:

  1. The old container should not run. Stop it, then start the new one on the same port: docker stop OLD && docker rm OLD. Check first that nothing depends on it.
  2. Both should run. Publish the new one on a different host port. The container port stays the same:
# Host port 8081 forwards to port 80 inside the container
docker run -d --name ob-port-b -p 8081:80 nginx:1.27-alpine
  1. Only local access is needed. Bind to the loopback address, so the port is not exposed on every interface: -p 127.0.0.1:8081:80. Two containers can use the same port number on different host addresses.
  2. Any free port will do (tests, CI): -p 80 or -P lets Docker choose a free host port. Read it back with docker port NAME.

In Compose, change the left side of the mapping, for example "8081:80", or read it from a variable: "${WEB_PORT:-8080}:80".

5. Docker Desktop on Windows

On Windows, Docker Desktop can fail with a message that ends in An attempt was made to access a socket in a way forbidden by its access permissions. Windows reserves port ranges for Hyper-V and other features, and a reserved port cannot be bound even when nothing listens on it. This case was not reproduced on the test machine; the check comes from the Windows command reference.

# Run in an elevated PowerShell or Command Prompt on Windows: list reserved TCP port ranges
netsh interface ipv4 show excludedportrange protocol=tcp

If your port falls inside a listed range, publish a port outside it.

6. Verify

# The mapping Docker actually set up
docker port ob-port-b
# Real output from the test machine
80/tcp -> 0.0.0.0:8081
80/tcp -> [::]:8081
# Expect HTTP 200 from the new container
curl -s -o /dev/null -w 'http %{http_code}\n' http://127.0.0.1:8081/

Also confirm that the original owner of the port still works if you left it running.

7. Rollback and prevention

  • Rollback: remove the new container (docker rm -f NAME) and start whatever you stopped in section 4 with its original command or Compose file.
  • Keep a port map per host: which service owns which host port. A short table in the repository is enough.
  • Use variables for host ports in Compose, so two copies of a project (for example two branches) can run side by side.
  • Prefer 127.0.0.1: bindings for services that only the host or a reverse proxy should reach.

References

Official reference

docs.docker.com ↗

Technical steps are original explanations; consult the upstream documentation for version-specific details.

Behavior differs by distribution and tool version. Commands are examples for authorized systems; review output for secrets before sharing.

Found this useful?

Follow us on YouTube for video explainers, and find us on Facebook to keep up with what is new.