Docker name is already in use: identify the stale container owner

The symptoms

• •`docker run --name <name> ...` aborts with "docker: Error response from daemon: Conflict. The container name '<name>' is already in use by container '<hash>'..." even though no container is currently running.
• •`docker ps` shows no entry for the name, but `docker ps -a` includes a stopped container with that exact name, frequently in Exited (137) or Exited (1) state.
• •Stack composition tools such as `docker-compose up` or `nerdctl run` fail with the same Conflict response because the name is still reserved on the local Docker daemon's name registry.
• •Re-running the same command after a host reboot reproduces the conflict, proving the name is persisted across daemon restarts rather than leaked from a running process.

Likely causes

• •A previous container with the requested name is stopped but not removed, so the daemon still holds the name-to-id mapping in its local store.
• •Two compose projects, scripts, or CI jobs raced on the same container name and one left a stopped container behind while the other tries to recreate it.
• •A crashed or OOM-killed container was never explicitly cleaned up, leaving it in Created or Exited state but still occupying the name.
• •A container was started with `--restart unless-stopped` (or a similar policy) and keeps respawning under the same name, but is captured only in `docker ps -a` during a brief crash loop window.

First ten minutes

1. 01Reproduce the error exactly: run the original `docker run --name <name> ...` invocation again and capture the full daemon response, including the conflicting container ID hash.
2. 02List all containers, including stopped ones, with `docker ps -a --filter name=<name>` to confirm the name is bound to a known container rather than a phantom entry.
3. 03Check the live state with `docker ps --filter name=<name>` and compare to the `-a` output to determine whether the owner is running, restarting, or stopped.
4. 04Inspect the suspected owner's metadata with `docker inspect <hash>` and read the `State.Status`, `State.ExitCode`, `State.StartedAt`, `State.FinishedAt`, and `Name` fields before naming it as the culprit.
5. 05Record the conflicting hash, image, and exit code so the subsequent removal decision can be justified by evidence rather than guesswork.

Evidence to collect

• •The conflicting container ID hash printed in the daemon's "already in use by container '<hash>'" message.
• •The `State.Status`, `State.ExitCode`, `State.StartedAt`, `State.FinishedAt`, and `State.Restarting` fields from `docker inspect` for that container.
• •The container's `Config.Image` and the `HostConfig.RestartPolicy.Name` value, to confirm whether a restart policy is actively respawning it.
• •The `Name` field from `docker inspect`, to confirm it matches the requested name byte-for-byte (no trailing whitespace or case drift).
• •Creation time (`CreatedAt`) of the existing container, to distinguish a recent crash from a long-forgotten leftover.

Where to look

• •The local Docker daemon's name registry, surfaced through `docker ps -a` and `docker inspect`, not the Docker image registry or any remote registry.
• •The `containers/` directory of the Docker root data directory (commonly `/var/lib/docker/containers/` on Linux), which persists name ownership across daemon restarts.
• •The orchestration layer that issued the `docker run` call — `docker-compose.yml`, `compose.yaml`, systemd unit, CI job definition, or shell script — to identify who is expected to own the name.
• •The host's process table, when a restart policy is suspected, to see whether a container runtime process is still alive and respawning the container.
• •Docker daemon logs at the configured log driver target, to correlate the conflict timestamp with the last start/exit event of the suspected owner.

Diagnostic steps

1. 01Compare `docker ps -a` output for the name against `docker ps` output to decide whether the owner is live, stopped, or restarting; a stopped entry with a non-zero exit code is the typical stale-owner case.
2. 02Read `State.Status` from `docker inspect`: values `exited`, `dead`, or `created` indicate the container is not running and the name is held only by the daemon's registry.
3. 03Read `HostConfig.RestartPolicy.Name`: a value of `always` or `unless-stopped` combined with a recent `State.FinishedAt` means the container is in a crash loop and will reclaim the name, so a plain `docker rm` will be undermined by the next restart.
4. 04Cross-check the conflicting hash from the error message against the `Id` field of the inspect output; if they differ, treat the error as evidence of a name collision across multiple owners rather than a single stale entry.
5. 05Check the orchestration source for the expected container name: a `container_name:` in a compose file, a `--name` flag in a script, or a hard-coded name in a CI definition, to confirm the new request is legitimate and the existing owner is the stale one.

Common mistakes

• •Assuming the error means a port collision or an image pull failure and changing the wrong layer of the stack instead of identifying the current name owner.
• •Blindly running `docker rm -f <name>` without first inspecting the conflicting container, which can destroy a peer application's state if the name is reused across services.
• •Renaming the new container to avoid the conflict instead of resolving the stale owner, which leaves the orphaned container on the host and shifts the problem to the next deploy.
• •Ignoring the restart policy field in `docker inspect`, then wondering why the conflict reappears within seconds because the existing container is being respawned by the daemon.
• •Trusting a GUI dashboard that only shows running containers and concluding nothing holds the name, when `docker ps -a` would have shown a stopped entry.

Safe fixes

• •If the existing container is stopped (`State.Status` in `exited`, `dead`, or `created`) and no restart policy will respawn it, stop the name owner first with `docker stop <hash>` then remove it with `docker rm <hash>`, then re-run the original `docker run --name <name> ...` invocation.
• •If the existing container is governed by a restart policy, update the orchestration definition to reference a new container name rather than fighting the automatic respawn, or change the restart policy to `no` before removal.
• •If two compose projects legitimately share the host, replace the hard-coded `container_name:` in one of them with a parameterized name so the daemon can assign a unique name per instance.
• •After removal, verify the name is free with `docker ps -a --filter name=<name>` returning an empty result before reissuing the `docker run` command that previously failed.
• •Add a post-deploy cleanup step, such as `docker rm <hash>` after `docker stop` succeeds, to the pipeline that owns the name so the next run starts on a clean name registry.

Prove the fix

1. 01Re-run the original `docker run --name <name> ...` command and observe that the daemon accepts the name and returns a new container ID without the "already in use" message.
2. 02Confirm with `docker ps --filter name=<name>` that the new container is listed in the active set with the expected image and `State.Status` of `running`.
3. 03Confirm with `docker ps -a --filter name=<name>` that exactly one container holds the name and that its `Id` matches the new container, not the predecessor.
4. 04Capture the daemon's response to the recreated run command and the inspect output of the new container as durable evidence that the name ownership has transferred.

Prevention and next steps

• •Use a name-uniqueness strategy in compose and CI files: either omit `container_name:` so the daemon assigns a unique name, or include a build identifier, commit hash, or run index in the name.
• •Adopt a convention of `docker rm` after `docker stop` on the named container at the end of every job, so the daemon's name registry is released between runs.
• •Audit the host periodically with `docker ps -a --filter status=exited` to find stale containers that still hold names and surface them before they cause a conflict.
• •Prefer immutable, per-run container names over stable names for short-lived workloads, so a conflict is structurally impossible rather than policy-enforced.

Safe commands and checks

docker run --name <name> <image>
docker ps -a --filter name=<name>
docker ps --filter name=<name>
docker inspect <hash>
docker stop <hash>
docker rm <hash>