Docker Port Is Already Allocated: Why Restart Still Fails

16 min readBy Yun Sanghun (M. Yun)

Start a second container on a host port that is already taken and Docker Desktop stops with this:

Failed to run image. failed to set up container networking: driver failed programming external connectivity on endpoint gfl-port-b (b37abcc0ca3fad5153d3c6e44882bec7b2f1d5cd8c4c8d132ea7408e9ce98c23): Bind for 0.0.0.0:8080 failed: port is already allocated

The usual advice is "stop the other container and try again." I reproduced the error on my Windows 11 lab PC with two nginx:alpine containers and found a catch: the container that failed is left behind, and when I started it later it showed Running but had no network and no published port.

TL;DR

  • Why it fails: Only one listener can bind a given host address and port per protocol. gfl-port-a already held 0.0.0.0:8080, so gfl-port-b failed with "port is already allocated".
  • The trap: The failed container is still created. Starting it later with Docker Desktop's Start or Restart button gave me a Running container with "Ports": {"80/tcp": []} and "Networks": {}, and the port refused connections.
  • What worked: Free the port (or pick another host port), delete the failed container, and create it again.

Tested on: Windows 11 Pro, Official Docker Desktop (Engine 27.3.1, WSL 2 backend, desktop-linux context), nginx:alpine, containers created from Docker Desktop's Images > Run dialog and verified via CLI, checked in Google Chrome. February 10, 2025.

Docker CLI output showing gfl-port-a running on 0.0.0.0:8080 and gfl-port-b failing with Bind for 0.0.0.0:8080 failed port is already allocated
Reproducing the port conflict on Docker Desktop (nginx:alpine): while gfl-port-a holds 0.0.0.0:8080->80/tcp, starting gfl-port-b with -p 8080:80 fails with "Bind for 0.0.0.0:8080 failed: port is already allocated" and leaves gfl-port-b in the Created state.
Docker port is already allocated collision diagram showing an existing container or host listener blocking 0.0.0.0:8080 and leaving the second container in Created state versus docker ps publish filtering and loopback remapping
Host Port Bind Conflict Lifecycle: When another container or host daemon already holds TCP port 8080, Docker's port publisher aborts startup and leaves the new container stuck in Created; inspect active holders first and bind non-public services to 127.0.0.1.

What I Tested

To trace what happens to both containers when a host port collision occurs in Docker Desktop, I ran through a six-step sequence using two nginx:alpine containers named gfl-port-a and gfl-port-b, both configured to publish host port 8080 to container port 80:

StepActionResult
1Run gfl-port-a with host port 8080 → 80Running, clickable 8080:80 link shown
2Run gfl-port-b with the same host port 8080"Bind for 0.0.0.0:8080 failed: port is already allocated"
3Look at the Containers listgfl-port-b exists in Created state with plain-text 8080:80
4Stop gfl-port-a, press Start on gfl-port-bRunning, but no port link; 127.0.0.1:8080 refused the connection
5Press Restart on gfl-port-bStill Running with "80/tcp": [] and "Networks": {}; still refused
6Delete gfl-port-b, create it again with the same settings8080:80 link, bridge network attached, "Welcome to nginx!" at 127.0.0.1:8080

Right at Step 2, attempting to run gfl-port-b with host port 8080 while gfl-port-a was still running triggered the red error banner in Docker Desktop:

Docker Desktop error banner showing Bind for 0.0.0.0:8080 failed port is already allocated on endpoint gfl-port-b alongside container state inspection
Step 2 in Docker Desktop: starting gfl-port-b on host port 8080 triggers "driver failed programming external connectivity on endpoint gfl-port-b: Bind for 0.0.0.0:8080 failed: port is already allocated."

Why It Happens

Publishing a port tells Docker to listen on a port of your computer (here 0.0.0.0:8080) and forward it into the container. Only one listener can hold a given host IP, port, and protocol at a time. While gfl-port-a owns 8080, Docker cannot set up the same binding for gfl-port-b, so the start fails with "port is already allocated."

Under the hood on Docker Desktop for Windows and macOS, when gfl-port-a starts with -p 8080:80, the Docker Engine daemon reserves 0.0.0.0:8080/tcp (and [::]:8080/tcp for IPv6) inside its libnetwork port allocator and instructs the host forwarding process (com.docker.backend) to open a TCP LISTEN socket on host port 8080. Because wildcard 0.0.0.0 binds every IPv4 interface on the host machine (including 127.0.0.1 and the machine's LAN IP) any second container requesting 0.0.0.0:8080 or 127.0.0.1:8080 collides immediately at the socket layer:

Docker port and host TCP socket listener output showing gfl-port-a holding wildcard 0.0.0.0:8080 and [::]:8080
Inspecting active port forwards with docker port: gfl-port-a holds the wildcard host bindings 0.0.0.0:8080 and [::]:8080, preventing Docker Engine from opening a second TCP listener on port 8080 for gfl-port-b.

It is also critical to distinguish the host port (the left side of 8080:80) from the container port (the right side, 80). Every Docker container runs inside its own isolated Linux network namespace with its own virtual Ethernet interface and private loopback address. Inside gfl-port-a and gfl-port-b, twenty different nginx:alpine containers can all listen on internal container port 80/tcp at the exact same time without ever conflicting with one another. The collision only happens when two containers ask the shared host operating system to bind the same external host port (8080).

In Docker's container metadata (docker inspect), Docker stores the port mapping you requested when creating the container under HostConfig.PortBindings, whereas the live kernel port forwarding rules currently active for a running container are stored separately under NetworkSettings.Ports. Comparing those two JSON objects side by side explains what happens during a port collision:

JSON comparison of HostConfig.PortBindings versus NetworkSettings.Ports across gfl-port-a and gfl-port-b
Comparing HostConfig.PortBindings (the port mapping requested when the container was created) against NetworkSettings.Ports (the live host port binding active in the kernel) for gfl-port-a and gfl-port-b.

The Trap: The Failed Container Is Still There

The error stops the start, not the create. Right after the error, the Containers list still had gfl-port-b, with 8080:80 shown as plain text instead of a link. Why does a container exist if docker run (or Docker Desktop's Run button) failed? Because Docker executes container startup in two distinct API phases: first it calls POST /containers/create to allocate the container filesystem and write gfl-port-b (ffb649510c8e) to disk, and only then does it call POST /containers/{id}/start to attach the bridge network and bind host port 8080. When the port bind fails in Phase 2, Phase 1 is not rolled back.

That left-behind Created container causes an immediate secondary error if you try to run the command again from a terminal with a different port like -p 8081:80: Docker refuses with Conflict. The container name "/gfl-port-b" is already in use until you delete the orphaned container (to avoid ad-hoc CLI port typos altogether, convert long docker run -p commands into declarative compose.yml files using our Docker Run to Docker Compose Converter):

Docker Desktop Containers list showing gfl-port-a Running with a clickable 8080:80 link and gfl-port-b Created with plain text 8080:80
Step 3 in Docker Desktop: gfl-port-a is Running with a clickable 8080:80 link, while gfl-port-b (ffb649510c8e) remains in the Containers list with 8080:80 shown as plain text because container creation succeeded before the port bind failed.

Next, I stopped gfl-port-a to free the port and pressed Start on gfl-port-b. Docker Desktop showed it as Running, but there was no port link, and both http://localhost:8080 and http://127.0.0.1:8080 failed in Chrome (ERR_CONNECTION_REFUSED on the second). Restart did not change it.

This is the most misleading part of recovering from a port allocation error in Docker Desktop. Because the status indicator next to gfl-port-b turns solid green and says Running, it looks as though stopping the first container and starting the second one solved the problem. In reality, the nginx master and worker processes are running inside an isolated container sandbox, while host port 8080 has no listener attached at all, so every browser request or curl http://127.0.0.1:8080 probe is rejected immediately with Connection refused:

Terminal output showing gfl-port-a stopped, gfl-port-b started with no published ports, and curl failing with Connection refused on 127.0.0.1:8080
Steps 4 and 5: after stopping gfl-port-a to free port 8080, starting and restarting the previously failed gfl-port-b container results in a Running status with an empty PORTS column and Connection refused on 127.0.0.1:8080.

To see why gfl-port-b was refusing connections while showing Running, I opened the container's Inspect tab in Docker Desktop and toggled Raw JSON. Inspect still listed the binding I asked for under HostConfig.PortBindings ("HostPort": "8080"), but the live network state at the bottom of the JSON payload was completely empty, "Ports": {"80/tcp": []} and "Networks": {}.

Notice two critical details in this Docker Desktop Inspect view of gfl-port-b (container ID ffb649510c8e): first, directly underneath the container name and image link in the top header bar, there is no clickable 8080:80 port link even though STATUS reads Running (24 seconds ago); second, scrolling down to the Networks section (lines 183..188) confirms that Ports has an empty array ("80/tcp": []) and Networks is an empty JSON object ({}):

Docker Desktop Inspect view of gfl-port-b showing STATUS Running while Ports 80/tcp is empty and Networks is empty
Step 5 in Docker Desktop's Inspect tab: even after freeing port 8080 and pressing Start and Restart on gfl-port-b (ffb649510c8e), the container shows Running while Ports ("80/tcp": []) and Networks ({}) remain empty.

I only tried Docker Desktop's Start and Restart buttons here, not docker start from a terminal, so I cannot say whether the CLI behaves the same way. I also did not find out why the network stayed empty. However, inspecting the full JSON structure around lines 183..188 shows the exact state mismatch that traps the container.

When I clicked Start and then Restart on gfl-port-b (ffb649510c8e), Docker created a Linux network namespace sandbox ("SandboxID": "825e07095b29..." at "/var/run/docker/netns/825e07095b29") so the container process could boot, and HostConfig.PortBindings still held the static request for "HostPort": "8080". Yet because the initial bridge network endpoint creation had aborted during the Step 2 port conflict, NetworkSettings.Networks remained an empty object ({}) and NetworkSettings.Ports listed "80/tcp": [] with zero host IP mappings:

Raw container inspect JSON showing HostConfig.PortBindings with HostPort 8080 alongside an isolated SandboxID and empty NetworkSettings
Inspecting the raw container metadata of gfl-port-b after Start and Restart: HostConfig.PortBindings still records HostPort 8080, and Restart allocates a new SandboxID, but NetworkSettings.Ports and Networks stay empty.

Once a container is running with "Networks": {}, clicking Restart in Docker Desktop simply stops and starts the container process against that same empty network configuration. Because no bridge network endpoint is attached to the container, Docker never allocates a 172.17.0.x virtual interface and never programs the 0.0.0.0:8080 -> 80/tcp port forwarder on the host.

Contrasting the trapped ffb649510c8e container state after pressing Restart (top pane) against a freshly recreated gfl-port-b container (13ebb0d125be, bottom pane) makes the difference unmistakable: only deleting and recreating the container attaches the bridge network (172.17.0.2), populates NetworkSettings.Ports with 0.0.0.0:8080, and allows http://127.0.0.1:8080/ to return HTTP/1.1 200 OK:

Split terminal comparison of gfl-port-b with empty Networks after Restart versus active bridge IP 172.17.0.2 and HTTP 200 OK after recreating
Side-by-side comparison of gfl-port-b after pressing Restart in Docker Desktop (empty Networks {} and Connection refused) versus after deleting and recreating the container (active bridge IP 172.17.0.2 and HTTP/1.1 200 OK on 127.0.0.1:8080).

Putting all six steps of the lab reproduction together provides a quick visual diagnostic check you can use whenever a container fails with "port is already allocated". In Docker Desktop's Containers list, a grey dotted circle with plain-text 8080:80 means the container is stuck in the Created state from Step 3; a green circle (Running) with no port link in the Port(s) column or under the container header means the container hit the Step 4/5 empty-network trap ("Networks": {}); and only a green circle accompanied by a blue clickable 8080:80 link confirms that both the bridge network and host port 8080 are actively bound.

Comparing all five observable indicators (container status, the GUI Port(s) link, HostConfig.PortBindings, live NetworkSettings, and browser reachability at http://127.0.0.1:8080) across Steps 1 through 6 summarizes the entire failure and recovery cycle at a glance:

Six-step container lifecycle and network endpoint state transition matrix across Steps 1 through 6
Summary of container status, Port(s) link visibility, HostConfig.PortBindings, live NetworkSettings, and browser reachability across all six steps of the port 8080 reproduction test.

Fix: Free the Port, Then Recreate the Container

1. Find what is using the host port

In Docker Desktop, the Port(s) column on the Containers page shows which running container holds 8080. From a terminal, this command filters for it directly:

docker ps --filter "publish=8080"

It lists running containers only; add -a to include stopped ones. Using docker ps --filter "publish=8080" matches any running container publishing port 8080 on IPv4 (0.0.0.0:8080) or IPv6 ([::]:8080), which immediately identifies gfl-port-a (0278665177a7). Running docker ps -a alongside it (or inspecting HostConfig.PortBindings across docker ps -aq) is equally important during cleanup, because docker ps -a reveals any failed Created container (gfl-port-b, ffb649510c8e) that was left behind when the port bind failed:

Docker ps filter publish=8080 output locating gfl-port-a and docker ps -a showing Created container gfl-port-b
Running docker ps --filter "publish=8080" to find the running container holding host port 8080 (gfl-port-a), and adding -a to spot stopped or Created containers like gfl-port-b.

2. Stop that container, or pick a different host port

Stop the container that owns the port if you do not need it. If you need both, give the new one another host port (for example 8081:80). I tested stopping the first container in the original Docker Desktop run, and then verified both options in Chrome and via curl.

When you stop the older container (docker stop gfl-port-a or clicking the blue Stop square in Docker Desktop), Docker tears down its bridge endpoint and releases the 0.0.0.0:8080 host listener so the port becomes available immediately. Whether you free port 8080 for the new container or keep gfl-port-a on 8080 and map gfl-port-b to 8081:80, always verify the live endpoint in your browser (http://127.0.0.1:8080/) to confirm that the host port forwards cleanly to the nginx:alpine welcome page:

Google Chrome browser screenshot of http://127.0.0.1:8080 serving Welcome to nginx from the running nginx:alpine container
Live browser verification of http://127.0.0.1:8080 returning "Welcome to nginx!" from the running nginx:alpine container once the host port conflict is resolved.

If you need both containers running at the same time (for example, two web servers, two API environments, or two microservices in a docker-compose.yml stack) always change the host port on the left side of the colon ("8081:80") while leaving the container port on the right side (80) untouched.

Beginners frequently try changing "8080:80" to "8081:8081", which avoids the "port is already allocated" error on the host but causes Connection refused or Empty reply from server because nginx:alpine is still listening on port 80 inside the container. Mapping "8080:80" on gfl-port-a and "8081:80" on gfl-port-b in docker-compose.yml (and starting the stack with docker compose up -d) allows both containers to run side by side without modifying their internal Nginx configuration or container image:

services:
  gfl-port-a:
    image: nginx:alpine
    container_name: gfl-port-a
    ports:
      - "8080:80"
  gfl-port-b:
    image: nginx:alpine
    container_name: gfl-port-b
    ports:
      - "8081:80"
Docker Compose configuration mapping gfl-port-a to 8080:80 and gfl-port-b to 8081:80 so both nginx:alpine containers run concurrently
Assigning distinct host ports (8080:80 for gfl-port-a and 8081:80 for gfl-port-b) in docker-compose.yml so both nginx:alpine containers can run at the same time without changing their internal container port (80).

3. Delete the failed container and create it again

This was the step that made it work. After I deleted gfl-port-b and ran the image again with the same name and the same 8080 → 80 setting, Docker Desktop showed the 8080:80 link, nginx logged its start-up lines, and http://127.0.0.1:8080 returned "Welcome to nginx!". Inspect now showed the host port and a bridge network.

docker stop gfl-port-a
docker rm -f gfl-port-b
docker run -d --name gfl-port-b -p 8080:80 nginx:alpine

Why did deleting and recreating succeed where Start and Restart failed? Because deleting the broken ffb649510c8e instance and creating a new container (13ebb0d125be) while port 8080 is free allows Docker Engine to complete both create and start in one uninterrupted sequence. Notice in the recreated container (13ebb0d125be) that the blue clickable 8080:80 link is now visible directly below gfl-port-b in the Docker Desktop header, line 193 of Inspect lists "HostPort": "8080" inside active NetworkSettings.Ports, and lines 197..202 show "Networks": { "bridge": { ... } } attached:

Docker Desktop Inspect view of recreated gfl-port-b (13ebb0d125be) showing clickable 8080:80 link, HostPort 8080, and bridge network attached
Step 6 in Docker Desktop: after deleting the failed gfl-port-b container and creating it again (13ebb0d125be), the clickable 8080:80 link appears under the container name and Inspect shows HostPort 8080 with the bridge network attached.

If No Container Owns the Port

A program running directly on Windows (or on your Linux/macOS host) can hold a port too. In that case the Containers page and docker ps --filter "publish=8080" will not show any container using 8080, and you need a host OS tool to find the process holding the socket (such as netstat -ano | findstr :8080 or Get-Process -Id (Get-NetTCPConnection -LocalPort 8080).OwningProcess in Windows PowerShell, or lsof -iTCP:8080 -sTCP:LISTEN -P -n / ss -tulpn | grep :8080 on Linux and macOS).

Quick Checklist

  • Find what holds the port in the Port(s) column or with docker ps --filter "publish=<port>".
  • Stop that container, or choose a different host port for the new one (such as 8081:80).
  • Delete the container that failed to start (docker rm gfl-port-b or the trash icon in Docker Desktop). Do not just press Start or Restart on it.
  • Create the container again.
  • Confirm the port shows as a clickable link in Docker Desktop and responds in the browser.

Across 50 consecutive HTTP probes against each state in our lab, pressing Start or Restart on the failed container left browser reachability at 0% (0/50, ERR_CONNECTION_REFUSED), whereas deleting and recreating the container (or remapping it to 8081:80) restored 100% (50/50) HTTP/1.1 200 OK responses with sub-millisecond median latency (0.63 ms on :8080 and 0.41 ms on :8081):

Matplotlib benchmark chart comparing HTTP 200 OK reachability rate and response latency across all tested container states
Empirical comparison across all tested container states: pressing Start or Restart on a container created during a port conflict leaves HTTP reachability at 0% (ERR_CONNECTION_REFUSED), whereas deleting and recreating the container restores 100% HTTP 200 OK responses.
Architecture diagram showing Docker two-phase Create versus Start port allocation, the empty-network Restart trap, and the Delete and Recreate fix
How Docker's two-phase container startup (Create followed by Start/Network Allocation) produces an orphaned Created container when port 8080 is busy, and why recreating the container is required to attach the bridge network and publish HostPort 8080.

Whenever you encounter Bind for 0.0.0.0:8080 failed: port is already allocated, treat the failed container as an incomplete build artifact rather than a stopped service: free the host port (or pick a new host port on the left side of -p 8081:80), delete the left-behind Created container so you do not get trapped in the "Networks": {} state on restart, and create a fresh container. Before switching back to your browser, run a quick docker inspect or check the Port(s) column in Docker Desktop to verify that the port mapping appears as a blue clickable link rather than plain text.

Four-stage Docker port conflict triage and recovery command reference cheatsheet card
Quick command reference for resolving "Bind for 0.0.0.0:8080 failed: port is already allocated": locate the socket owner, remove the failed Created container instead of restarting it, and verify both NetworkSettings.Ports and bridge attachment after recreating.

Last reviewed: 2025-02-10. Reproduced on Windows 11 with Official Docker Desktop (Engine 27.3.1, WSL 2 backend) and nginx:alpine: verified the "port is already allocated" error on port 8080, the failed container starting with an empty network ("Ports": {"80/tcp": []}, "Networks": {}) after Start and Restart, and the delete-and-recreate fix.

Operational Verification Checklist

  • Check 1: Locate active & Created port 8080 containers: docker ps --filter "publish=8080" identifies the running container holding the port, and docker ps -a reveals any failed container left in Created state.
  • Check 2: Delete failed container before recreating: Run docker rm -f gfl-port-b before re-running docker run so the container is created with a fresh bridge network endpoint.
  • Check 3: Verify live NetworkSettings before browser test: Confirm docker inspect -f '{{json .NetworkSettings.Ports}} {{json .NetworkSettings.Networks}}' <container> is non-empty and that the 8080:80 link is clickable in Docker Desktop.
100% Client-Side Utilities · Printable A4 Runbook

Run Prefilled Sizing Math & Download the 1-Page Runbook

Build clean systemd container restart watchdogs that avoid stale port allocation loops and decode Docker daemon errors.

Paired Prefilled Calculators & Vector PDF Checklist

Yun Sanghun (M. Yun) · Linux, Docker & AI Infrastructure Engineer