Docker Compose KeyError: ContainerConfig: Migrate from docker-compose v1

Confirm which Compose is actually running#

The command spelling is evidence:

Docker’s retired products documentation says Compose v1 is no longer maintained and has been superseded by Compose v2. The Compose history also distinguishes the CLI version from the Compose Specification, so a top-level version: field in the YAML is not the same thing as the installed CLI version.

Migrate to the current docker compose command#

Use the installation method appropriate for the host: current Docker Desktop bundles Compose, while Linux installations can use the Docker CLI plugin. After installing, verify the binary before touching the project:

1
docker compose version
2
docker compose config --quiet

Then run the same project with the space-separated command:

1
docker compose pull
2
docker compose up -d

docker compose config --quiet validates the rendered model without starting the services. If it reports an environment or syntax problem, fix that output separately; it is not the ContainerConfig traceback.

For a CI runner or server, check all execution paths:

1
rg -n --hidden --glob '!node_modules' 'docker-compose|docker compose' .

Search deployment scripts, systemd units, Makefiles, cron entries, and CI workflows. A local shell can use v2 while a scheduled job still invokes the old hyphenated binary.

Recreate containers without deleting volumes#

The Compose issue that popularized this traceback shows a Python Compose 1.29.2 process failing while it tried to read old container volume metadata after an image update. Once the CLI is migrated, recreate the project state in a controlled order:

1
docker compose ps
2
docker compose config --services
3
docker compose down
4
docker compose up -d

The plain down command removes the project containers and network but keeps named volumes unless you explicitly ask for volume removal. Before any destructive cleanup, record the project name, volume names, and backup status:

1
docker volume ls
2
docker compose config --volumes
3
docker compose ps -a

If an orphaned container from an earlier project definition is the actual problem, review the list first and then use --remove-orphans deliberately:

1
docker compose up -d --remove-orphans

Do not add -v unless you have confirmed that every project volume is disposable or backed up. Removing a container is not the same as removing the database stored in its named volume.

If v2 still fails, follow the new inner error#

Moving from v1 should remove the specific Python ContainerConfig path. If docker compose still fails, do not keep repeating the old fix. Capture:

1
docker version
2
docker compose version
3
docker compose config
4
docker compose ps -a

Then classify the new failure:

• a rendered variable is empty: check the Compose interpolation inputs and --env-file boundary;
• a service starts before its dependency is ready: add a real healthcheck and service_healthy condition;
• an image cannot be pulled or recreated: inspect the image reference, registry credentials, and container logs;
• a volume cannot be mounted: inspect the host path and the user running Docker.

The existing Compose interpolation guide covers variables that are empty during parsing. For a database that is created before it is ready, use the Compose healthcheck guide instead. Those are different boundaries from a retired CLI traceback.

Keep the migration reproducible#

Once the project starts under Compose v2, make the command part of the repository workflow rather than relying on developer memory:

1. Document the minimum Docker Desktop or Compose plugin version that the project actually tests.
2. Use docker compose in scripts and CI.
3. Run docker compose config --quiet before an automated deployment.
4. Keep named-volume backup and restore steps separate from container recreation.
5. Record the output of docker compose version when an upgrade changes behavior.

The takeaway is that KeyError: 'ContainerConfig' is usually a CLI compatibility signal, not a request to delete application data. Identify the legacy docker-compose path, migrate to docker compose, and only then clean up the specific stale containers that remain.

FAQ#