Docker Compose "KeyError: 'ContainerConfig'" - Fix Legacy Compose Recreate

The legacy Python docker-compose (v1) throws KeyError: 'ContainerConfig' when recreating a container whose image/metadata it can no longer reconcile. It is a known v1 bug; Compose v2 does not have it.

What this error means

An older docker-compose up/up -d fails with a Python traceback ending in KeyError: 'ContainerConfig', usually while recreating an existing container after an image change. A fresh environment with no existing containers works.

ERROR: for db  'ContainerConfig'
...
KeyError: 'ContainerConfig'

Common causes

Legacy compose v1 recreate bug

The Python v1 client mis-handles container metadata when recreating containers from a changed image, raising KeyError: 'ContainerConfig'. It is a defect in the deprecated v1 tool.

Stale containers/images from a prior run

Leftover containers created under different image metadata on a reused runner trigger the recreate path that exposes the bug.

How to fix it

Use Docker Compose v2

The Go-based docker compose (v2, a subcommand) does not have this bug. Switch off the legacy hyphenated v1 binary.

docker compose version       # v2 plugin
docker compose up -d         # instead of: docker-compose up -d

Recreate cleanly if stuck on v1

Tear down the existing containers so compose creates fresh ones instead of recreating.

docker-compose down --remove-orphans
docker-compose up -d --force-recreate

How to prevent it

• Use Docker Compose v2 (docker compose) in CI, not the legacy v1 docker-compose.
• Start from a clean container state on ephemeral runners.
• Pin image tags so recreate behavior is predictable.

Related guides