Breaking Key Change in Docker CLI Version Response

[superslowsoftware (Matthew Nash)]

Summary

With ansible community.docker the docker_compose_v2 module fails with KeyError: 'ApiVersion' when running against Docker Engine 29.0.0. The module’s version detection logic in common_cli.py is incompatible with the new JSON output format from Docker 29.x.

Issue Type

• Bug Report

Component Name

• docker_compose_v2 module
• common_cli.py (module_utils)

Ansible Version

ansible-core 2.16.5

Collection Version

community.docker: 4.2.0 & 5.0.1 (same behavior)

Docker Version (Target Host)

Client: Docker Engine - Community
 Version:           29.0.0
 API version:       1.52
 Go version:        go1.25.4
 Built:             Mon Nov 10 21:49:39 2025

Server: Docker Engine - Community
 Engine:
  Version:          29.0.0
  API version:      1.52 (minimum version 1.44)

OS / Environment

• Target Host: RHEL 9 / CentOS 9 (kernel 5.14.0-631.el9.x86_64)
• Target Python: 3.9
• Docker Compose: v2.40.3

Steps to Reproduce

1. Install Docker 29.0.0 on target host
2. Run playbook with community.docker.docker_compose_v2 module:

- name: Start docker compose cluster
  community.docker.docker_compose_v2:
    project_src: "/path/to/compose"
    files: "docker-compose.yml"
    project_name: "test_stack"
    state: "present"

3. Module fails with KeyError

Expected Results

Module successfully detects Docker version and executes compose commands.

Actual Results

KeyError: 'ApiVersion'
  File "ansible_collections/community/docker/plugins/modules/docker_compose_v2.py", line 625, in main
  File "ansible_collections/community/docker/plugins/module_utils/common_cli.py", line 303, in __init__
  File "ansible_collections/community/docker/plugins/module_utils/common_cli.py", line 83, in __init__
KeyError: 'ApiVersion'

Root Cause

Docker 29.0.0 changed the JSON output structure of docker version --format json. The parsing logic expects a consistent ApiVersion key, but Docker 29.x returns:

Client section:

{
  "Client": {
    "ApiVersion": "1.52",  // Still lowercase 'p'
    "DefaultAPIVersion": "1.52"
  }
}

Server section:

{
  "Server": {
    "APIVersion": "1.52",  // Now all-caps "API"
    "MinAPIVersion": "1.44",
    "Components": [
      {
        "Name": "Engine",
        "Details": {
          "ApiVersion": "1.52"  // Also exists here
        }
      }
    ]
  }
}

The module’s parsing in common_cli.py line 83 needs to be updated to handle both the old and new JSON structures.

Workaround

Downgrade to Docker 27.x (stable LTS version) or use shell commands instead of the module:

- name: Start docker compose cluster
  shell: |
    docker compose -f docker-compose.yml -p project_name up -d
  args:
    chdir: "/path/to/compose"

Suggested Fix

Update common_cli.py to check for both ApiVersion and APIVersion keys, and handle the new nested structure in Docker 29.x JSON output.

[meyay (Metin Y.)]

Like shared in this topic, I can’t reproduce a difference in the keys.

You can test it easily yourself:

# default version
curl --silent -XGET --unix-socket /run/docker.sock http://localhost/version | jq .

#  specific version
curl --silent -XGET --unix-socket /run/docker.sock http://localhost/v1.44/version | jq .

The output does not have the “Server” key that you have in your output.

Update (before even posting it): They use the output of the docker cli and don’t query the endpoint directly:

docker version --format '{{json .}}' | jq
{
    ...
  },
  "Server": {
    ...
    "Version": "29.0.0",
    "APIVersion": "1.52",
    "MinAPIVersion": "1.44",
    ...
    "Components": [
      {
        "Name": "Engine",
        "Version": "29.0.0",
        "Details": {
          "ApiVersion": "1.52",
          ... 
          "MinAPIVersion": "1.44",
           ...
        }
      },
...
    ]
  }
}

[meyay (Metin Y.)]

I raised an issue in Docker’s upstream project moby:

Docker CLI v29 Info json output has typo in "APIVersion" key

I managed to create a duplicate of an existing issue:

client ServerVersionResult struct missing JSON marshaling tags

[meyay (Metin Y.)]

You probably saw it already: the fix is included in the 29.0.1 release.