Docker Network Errors: "Endpoint Already Exists" / Sandboxes Left Behind

Docker's per-network bookkeeping gets stuck after failed restarts: containers half-exist in the network sandbox. The fix is targeted disconnect/prune, not daemon restarts.

What you'll see

Root causes

Stale network endpoint record from a crashed container

A container died without cleanup; the network endpoint persists and blocks the name. docker network inspect <net> lists endpoints — your container appears there without running.

Compose recreate raced / partially failed

docker compose up interrupted mid-recreate leaves the old endpoint attached. The name collision surfaces on the next up.

Fix it

  1. See what the network thinks exists
    docker network inspect <network> --format '{{range .Containers}}{{.Name}} {{end}}'
  2. Disconnect the stale endpoint
    docker network disconnect -f <network> <container> 2>/dev/null; docker rm -f <container> 2>/dev/null
  3. Clean unused networks and retry
    docker network prune -f && docker compose up -d
  4. If the default bridge is wedged, recreate the compose network explicitly
    docker compose down --remove-orphans && docker compose up -d   # down removes the project network

Field note

Avoid docker network prune on hosts where other projects share networks — disconnect the specific endpoint instead. Recurring staleness under OOM/brownout conditions usually means the host is memory-starved during deploys.

Common questions

Will restarting the Docker daemon fix it?

Usually yes, but it drops every container on the host. The targeted disconnect/rm sequence fixes the single wedged project without collateral downtime.

Why does this keep happening on deploys?

Deploys that recreate containers under memory pressure get killed mid-swap. Check dmesg for OOM kills around deploy times, and stagger recreate operations in CI.

Related fixes

Ship it right the first time

A production-shaped compose stack: healthchecks, resource limits, log rotation. Never debug a boot race again.

Docker Production Starter — $19 →

One-time. Yours to modify. Instant download from the NinjaOps template store.