Docker Compose KeyError: 'ContainerConfig' With --force-recreate

Problem Statement

When running docker-compose up -d --force-recreate, you may encounter a KeyError: 'ContainerConfig' error, particularly after system updates or Docker upgrades. This error typically appears with a traceback ending in:

File "compose/service.py", line 1579, in get_container_data_volumes
KeyError: 'ContainerConfig'

The puzzling aspect is that standard commands work without issues:

docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d

But this command consistently fails:

docker-compose -f docker-compose.prod.yml up -d --force-recreate

This issue commonly occurs with simple Redis configurations like:

version: '3.8'
services:
  redis:
    image: redis:latest
    restart: always
    ports:
      - "6379"

Solution

Primary Fix: Use Docker Compose v2

The root cause is legacy compatibility issues in Docker Compose v1 (docker-compose). The solution is to migrate to Docker Compose v2 (docker compose without hyphen):

# Replace this failing command:
docker-compose -f docker-compose.prod.yml up -d --force-recreate

# With this working v2 equivalent:
docker compose -f docker-compose.prod.yml up -d --force-recreate

Step-by-Step Migration Guide

DEPRECATION NOTICE

docker-compose (v1) was deprecated in 2021. Docker Compose v2 (docker compose) has been the standard since mid-2023.

1. Uninstall old Docker Compose v1

# Ubuntu/Debian systems
sudo apt-get remove docker-compose

# Manual installations (check default paths)
sudo rm /usr/local/bin/docker-compose

2. Install Docker Compose v2

bash

sudo apt-get update
sudo apt-get install docker-compose-plugin

bash

mkdir -p ~/.docker/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v2.26.1/docker-compose-$(uname -s)-$(uname -m) -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

3. Verify Installation

docker compose version
# Should output: Docker Compose version v2.26.1 (or higher)

Alternative Solution: Full Docker Reinstallation

If the above doesn't resolve the issue, perform a complete Docker upgrade:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl restart docker

Why This Works

The KeyError occurs because:

1. Docker Engine internals changed after updates
2. --force-recreate implementation in v1 has compatibility bugs
3. Volumes/bindings handling differs between versions

Version Differences

Feature	Docker Compose v1	Docker Compose v2
Command	docker-compose (hyphen)	docker compose (space)
Architecture	Standalone Python script	Docker CLI plugin
Maintenance	Deprecated since July 2023	Actively maintained
Container recreation	Buggy with --force-recreate	Correct implementation

Recommended Workflow

Always use Docker Compose v2 commands for production operations:

docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d --force-recreate --build

Avoid Mixing Versions

Don't alternate between docker-compose and docker compose commands. This causes configuration mismatches and persistent errors.

Troubleshooting Tips

If v2 commands aren't recognized:

# Verify installation path
ls -la ~/.docker/cli-plugins | grep compose

# Set global PATH if needed
sudo ln -s ~/.docker/cli-plugins/docker-compose /usr/bin/docker-compose-v2

For Windows/macOS users, use Docker Desktop (v4.4+) which bundles Compose v2 automatically. Verify through:

docker compose version