Docker "Conflict. The container name is already in use" in CI

By Daniel Zoghalchali·Latchkey

You started a container with a fixed --name, but a container with that name already exists. Docker names must be unique, so the daemon refuses to create a second one.

What this error means

A docker run --name <x> fails with Conflict. The container name "/<x>" is already in use by container .... It often appears on a re-run, or on a long-lived runner where a previous job left the container behind.

docker: Error response from daemon: Conflict. The container name "/postgres-test"
is already in use by container "a1b2c3...". You have to remove (or rename)
that container to be able to reuse that name.

Diagnose it: read the container, not the compose file

A container that exits immediately in CI has almost always logged the reason and then been cleaned up. Capture the logs and the exit code before changing configuration.

# why did it stop?
docker ps -a --format '{{.Names}}\t{{.Status}}\t{{.Image}}'
docker logs <container> 2>&1 | tail -50
docker inspect <container> --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}'

Common causes

A previous run left the container behind

A container started with the same --name was not removed (the job failed before cleanup, or --rm was not used), so the name is still taken on a reused runner.

Two steps use the same fixed name

Parallel or repeated steps that all hardcode the same --name collide, because only one container can hold that name at a time.

How to fix it

Remove the existing container first, or use --rm

Clean up before starting, and auto-remove on exit so the name frees up.

docker rm -f postgres-test 2>/dev/null || true
docker run --rm --name postgres-test -d postgres:16

Use unique names or let Docker assign one

1. Drop --name and let Docker generate a unique name, referencing the container by its ID.
2. Or suffix the name with a unique value (run id, timestamp).
3. Add a cleanup step that removes the container even when the job fails.

How to prevent it

• Use --rm for ephemeral CI containers so they self-clean.
• Avoid hardcoded --name values that can collide across runs/steps.
• Add an always-run cleanup step on long-lived runners.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation