The deploy that couldn't recreate its own container

An interrupted docker compose up leaves an orphaned, hash-prefixed container squatting a service name, so every later deploy fails to recreate it until someone removes it by hand. Adding --remove-orphans (or a pre-clean) lets the deploy heal its own stack instead of failing on state left by a previous run.

Two deploys in a row failed with the same Docker error, and neither was our code's fault. A container-name conflict wedged the whole stack. Here is what leaves it behind, and how to make the deploy heal itself.

The error

Container app  Recreate
Error response from daemon: Conflict. The container name
"/ab03b9ef_app" is already in use by container "4619ca...".

The image built fine. The failure was at the recreate step, and it stopped the deploy dead.

What leaves it behind

When docker compose up recreates a service, it renames the old container to a temporary <hash>_<name> before creating the new one and removing the old. If that sequence is interrupted — a killed deploy, a host reboot, an OOM — the renamed container survives. Now a container is squatting a name Compose expects to be free, and the next up cannot reclaim it. Every subsequent deploy hits the same conflict until someone removes the orphan by hand.

The one-line fix

Compose can clean this up itself:

docker compose up -d --build --remove-orphans

--remove-orphans removes containers for the project that are not in the current compose file — including the stray renamed leftover — before recreating. For defense in depth, add a pre-flight that force-removes any container whose name matches the service but is not the compose-managed one.

Why it is worth automating

It is not your code. A perfectly good release fails on host state left by a previous interrupted run. Without self-heal, every deploy is one bad interruption away from a manual host visit.
It fails at the worst time. The build succeeds, so you think you are deploying — then the recreate wedges, and if you have auto-rollback it kicks in and the release silently does not ship.
The manual fix does not scale. "SSH in and docker rm the orphan" is fine once. It is not a deploy strategy.

Takeaway

A deploy should be able to recover from its own interrupted previous run. If your recreate step can be wedged by a leftover container, add --remove-orphans (or a pre-clean) so the next deploy heals the stack instead of failing on it.