Fix Docker “failed to create shim task: address already in use”

Overview

This error typically appears during docker run or docker compose up:

• Cannot start service <name>: failed to create shim task: address already in use

It usually means one of the following:

• A host port you are publishing is already in use (most common).
• A stale containerd shim socket/process exists after a crash/restart.
• A Docker network overlaps with your LAN/VPN subnet, causing address conflicts.

Use the quickstart below to identify which case you have, then apply the targeted fix.

Quickstart (diagnose and fix)

1. Check for port-binding conflicts

• If the error includes listen tcp … bind: address already in use, find what holds the port:
  • Linux/macOS: ss -ltnp | grep :PORT or lsof -i :PORT
  • Windows PowerShell (Admin): netstat -ano | findstr :PORT
• Stop the conflicting process or change the host port mapping in your compose file.

1. Clear stale containerd shim (Linux or Docker Desktop)

• Look for messages like ttrpc: listen unix /run/containerd/s/... bind: address already in use.
• Restart Docker Engine (or Docker Desktop). If needed, kill lingering containerd-shim processes and remove stale sockets.

1. Fix network/IP conflicts

• If you use VPNs or custom subnets and startups hang/fail without a clear port, inspect Docker networks for overlapping subnets.
• Recreate networks with non-overlapping address pools and restart Docker.

Minimal working example (reproduce and fix a port conflict)

Compose file mapping port 8080 on the host to 8080 in the container:

version: "3.9"
services:
  web:
    image: python:3.11-alpine
    command: ["python", "-m", "http.server", "8080"]
    ports:
      - "8080:8080"

Reproduce the error by occupying the port, then starting Compose:

# In a terminal on the host
python3 -m http.server 8080 &  # holds TCP/8080 on the host

docker compose up
# You will see: failed to create shim task ... listen tcp 0.0.0.0:8080: bind: address already in use

Fix options:

• Stop the process using 8080, then docker compose up.
• Or change the mapping to a free port, e.g. 8081:8080, then docker compose up.

Symptom-to-fix map

Step-by-step fixes

1) Resolve host port conflicts

• Identify published ports in Compose:
  • ports:
    • "HOST:CONTAINER"
• Find what is using the host port.

Linux/macOS:

# Replace 8080 with your host port
ss -ltnp | grep :8080 || lsof -i :8080
# Stop the process or select another free port

Windows (PowerShell, run as Administrator):

netstat -ano | findstr :8080
# Note the PID, then stop the process in Task Manager or:
Stop-Process -Id <PID> -Force

Adjust Compose if needed:

ports:
  - "127.0.0.1:8081:8080"   # bind to a free port and only on localhost

Notes:

• Changing the container port rarely helps; the conflict is on the host side.
• Binding to 127.0.0.1 reduces conflicts with other listeners on different interfaces.

2) Clear stale containerd shim/socket

If you see ttrpc: listen unix /run/containerd/s/... bind: address already in use:

Linux:

# Restart Docker (and containerd if separate)
sudo systemctl restart docker
# If it persists, find and kill shim processes
ps -ef | grep containerd-shim
sudo kill -9 <shim_pid_1> <shim_pid_2>
# Remove stale sockets (careful—only files under /run/containerd/s)
sudo rm -f /run/containerd/s/*
sudo systemctl restart docker

Docker Desktop (macOS/Windows):

# From the UI: Quit and restart Docker Desktop
# Windows WSL2: reset networking stack
wsl --shutdown
# Then relaunch Docker Desktop

Compose cleanup:

docker compose down --remove-orphans
docker ps -a               # verify no stuck containers
docker system prune -f     # optional: removes unused data

3) Fix Docker network/subnet collisions

Symptoms: intermittent startup failures, containers cannot reach each other, or errors during network creation while on VPN.

Inspect networks and subnets:

docker network ls
docker network inspect bridge --format '{{(index .IPAM.Config 0).Subnet}}'

If your LAN/VPN uses the same space (e.g., 172.17.0.0/16), reconfigure Docker’s default pools.

Edit /etc/docker/daemon.json (Linux) or Docker Desktop settings (equivalent) to use non-overlapping pools:

{
  "default-address-pools": [
    { "base": "10.200.0.0/16", "size": 24 },
    { "base": "10.201.0.0/16", "size": 24 }
  ]
}

Apply changes:

sudo systemctl restart docker
# Recreate networks so new pools apply
docker network prune -f
# Then recreate your stack
docker compose down && docker compose up -d

4) Windows/WSL2 specific checks

• Port proxies can hold addresses unexpectedly.

netsh interface portproxy show all
# Remove stale proxy if needed
enetsh interface portproxy delete v4tov4 listenport=8080 listenaddress=0.0.0.0

• If Docker Desktop networking is confused: wsl --shutdown, then restart Docker Desktop.

5) Last-resort rebuild

If issues persist:

docker compose down --volumes --remove-orphans
docker network prune -f
docker system prune -af
sudo systemctl restart docker
# Or Docker Desktop: factory reset (as a last resort)

Pitfalls

• Killing the wrong PID on the host; confirm with ss/lsof/netstat before stopping.
• Using host network mode; it bypasses Docker’s port mapping and easily collides with host listeners.
• Overlapping custom networks created by multiple Compose projects.
• Forgetting to restart Docker after changing daemon.json.

Performance notes

• Publishing many host ports slows startup due to firewall/NAT rules. Prefer internal service-to-service communication on user-defined bridge networks and publish only what you need.
• Binding to 127.0.0.1 reduces firewall overhead compared to 0.0.0.0 when external access isn’t needed.
• Avoid rapid restart loops; they can leak shim processes/sockets on unstable hosts. Add restart delays/backoff.

FAQ

• Q: Changing the container port didn’t help. Why? A: The conflict is the host port you publish (left side of HOST:CONTAINER), not the container’s internal port.

• Q: Do I need to expose a port if services only talk internally? A: No. Use a user-defined network and service names; omit ports to avoid host conflicts entirely.

• Q: Is this a Docker bug? A: Stale shim sockets can occur after crashes. Restarting Docker and cleaning up shims/sockets resolves it.

• Q: How do I find which container publishes a port? A: docker ps shows PORTS. For details: docker inspect -f '{{ .NetworkSettings.Ports }}' <container>.

• Q: Can VPNs cause this error? A: Yes. Overlapping subnets between Docker networks and your VPN/LAN can prevent allocation; use non-overlapping address pools.