Docker: Port Is Already Allocated (tested)

This error means another container (or another process on the host) already has the host port you're trying to publish. Docker can't bind the same host port twice, so the second docker run fails before the new container ever starts.

1. Reproduced: the exact error

With one container already publishing host port 18089, starting a second container on the same port fails immediately:

docker run -d --name forever-port-test2 -p 18089:80 postgres:16-alpine

docker: Error response from daemon: failed to set up container networking:
driver failed programming external connectivity on endpoint forever-port-test2
(b786a9a7...): Bind for 0.0.0.0:18089 failed: port is already allocated.

The new container is never created — this fails at the networking setup step, before the image even runs.

2. Find out which container is holding the port

Before changing anything, confirm what's actually using it. docker ps with a port filter answers this directly:

docker ps --filter "publish=18089" --format "table {{.Names}}\t{{.Ports}}"

NAMES               PORTS
forever-port-test   0.0.0.0:18089->80/tcp, [::]:18089->80/tcp

If nothing shows up here but the error still happens, a non-Docker process on the host has the port — check with ss -ltnp (Linux) instead.

3. Fix 1: stop the container that's holding the port

If the existing container is disposable or you just forgot it was running, stop it and the port frees up immediately:

docker stop forever-port-test
docker run -d --name forever-port-test3 -p 18089:80 postgres:16-alpine
9bf47358272d...

docker ps --filter name=forever-port-test3 --format "{{.Names}} {{.Status}}"
forever-port-test3 Up Less than a second

We confirmed this: the second container started cleanly the moment the port was free, with no other changes.

4. Fix 2: publish a different host port instead

If you need both containers running at once, don't free the port — map the new container to a different host port and keep the same container port:

docker run -d --name forever-port-test4 -p 18090:80 postgres:16-alpine

This works with zero changes to the container image; only the -p host:container mapping changes. Use this when the two containers genuinely need to coexist, rather than stopping one to free the port.

5. Why this isn't a "docker restart" problem

A common mistake is assuming a crashed or stopped container released the port — it didn't, because the port is held until the container is removed, not just stopped, in the specific case of restarting with the exact same name and port mapping expecting a clean slate. In practice the error we reproduced happens with a running container holding the port; a stopped container with the same host port mapping does not block a new container from using that port, since Docker only reserves the port while the container's network endpoint is active. If you still get this error after stopping what you thought was the conflicting container, re-run the docker ps --filter publish= command from step 2 — something else, possibly unrelated, is using it.

Frequently asked questions

How do I find what's using a port without knowing the container name?

docker ps --filter "publish=PORT" --format "table {{.Names}}\t{{.Ports}}" lists every container publishing that port. We confirmed it returns the exact container name instantly, with no need to inspect each container individually.

What if docker ps shows nothing but I still get the error?

Then a non-Docker process on the host has the port. On Linux, ss -ltnp (or lsof -i :PORT) shows the owning process; Docker can't publish a container port to a host port that any process already holds.

Does stopping the container free the port immediately?

Yes, we confirmed this directly: docker stop released the port instantly, and a new container on the same host port started successfully right after, with no delay or retry needed.

Can I avoid this entirely?

Publish to a different host port (-p 18090:80 instead of -p 18089:80) if both containers need to run simultaneously. The container's internal port can stay the same; only the host-side number needs to be unique.

Is this the same as 'address already in use'?

They're closely related: 'port is already allocated' is Docker's own message when it won't even try to bind; the underlying OS-level error if Docker did try would be 'address already in use'. Either way, the fix is identical: free the port or pick a different one.

Written with AI assistance. Measured on 2026-10-03 with Docker Engine on Linux, using real containers (postgres:16-alpine). Every error message below is copy-pasted output, not paraphrased. PlainHeaders is our extension; Docker is free.