# Breaking Key Change in Docker CLI Version Response

**URL:** <https://forums.docker.com/t/breaking-key-change-in-docker-cli-version-response/150390>\
**Category:** General\
**Tags:** docker, build, docker-compose\
**Created:** [November 11, 2025, 9:18pm UTC](https://forums.docker.com/t/breaking-key-change-in-docker-cli-version-response/150390 "2025-11-11T21:18:32Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![superslowsoftware](https://sea3.discourse-cdn.com/docker/user_avatar/forums.docker.com/superslowsoftware/32/62329_2.png) [@superslowsoftware](https://forums.docker.com/u/superslowsoftware)\
**Post date:** [November 11, 2025, 9:18pm UTC](https://forums.docker.com/t/breaking-key-change-in-docker-cli-version-response/150390/1 "2025-11-11T21:18:32Z")

</div>

## 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

```auto
ansible-core 2.16.5

```

## Collection Version

```yaml
community.docker: 4.2.0 & 5.0.1 (same behavior)

```

## Docker Version (Target Host)

```auto
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:

```yaml
- 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"

```

1. Module fails with KeyError

## Expected Results

Module successfully detects Docker version and executes compose commands.

## Actual Results

```auto
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:**

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

```

**Server section:**

```json
{
  "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:

```yaml
- 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.

```auto

```

---

<div class="post-metadata">

**Author:** ![meyay](https://sea3.discourse-cdn.com/docker/user_avatar/forums.docker.com/meyay/32/34000_2.png) [@meyay](https://forums.docker.com/u/meyay)\
**Post date:** [November 11, 2025, 9:39pm UTC](https://forums.docker.com/t/breaking-key-change-in-docker-cli-version-response/150390/2 "2025-11-11T21:39:57Z")

</div>

Like shared in this [topic](https://forums.docker.com/t/docker-29-increased-minimum-api-version-breaks-traefik-reverse-proxy/150384/10), I can’t reproduce a difference in the keys.

You can test it easily yourself:

```auto
# 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:

```auto
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",
           ...
        }
      },
...
    ]
  }
}

```

---

<div class="post-metadata">

**Author:** ![meyay](https://sea3.discourse-cdn.com/docker/user_avatar/forums.docker.com/meyay/32/34000_2.png) [@meyay](https://forums.docker.com/u/meyay)\
**Post date:** [November 11, 2025, 10:01pm UTC](https://forums.docker.com/t/breaking-key-change-in-docker-cli-version-response/150390/3 "2025-11-11T22:01:34Z")

</div>

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

> <https://github.com/moby/moby/issues/51487>
>
> \### Description
> 
> With Docker 29.0.0. the key "ApiVersion" changed to APIVersion …in the Server block, which breaks client that rely on the output of \` docker version --format '{{json .}}'\`.
> 
> The discussion in https://forums.docker.com/t/breaking-key-change-in-docker-cli-version-response/150390 made me raise this issue.
> 
> Note: The Docker v29 api is not affected by the changed key name. 
> 
> 
> \### Reproduce
> 
> 1. docker version --format '{{json .}}' | jq
> {
> "Client": {
> "Platform": {
> "Name": "Docker Engine - Community"
> },
> "Version": "29.0.0",
> "ApiVersion": "1.44",
> "DefaultAPIVersion": "1.52",
> "GitCommit": "3d4129b",
> "GoVersion": "go1.25.4",
> "Os": "linux",
> "Arch": "amd64",
> "BuildTime": "Mon Nov 10 21:46:31 2025",
> "Context": "default"
> },
> "Server": {
> "Platform": {
> "Name": "Docker Engine - Community"
> },
> "Version": "29.0.0",
> "APIVersion": "1.52",
> "MinAPIVersion": "1.44",
> "Os": "linux",
> "Arch": "amd64",
> "Experimental": false,
> "Components": \[
> {
> "Name": "Engine",
> "Version": "29.0.0",
> "Details": {
> "ApiVersion": "1.52",
> "Arch": "amd64",
> "BuildTime": "Mon Nov 10 21:46:31 2025",
> "Experimental": "false",
> "GitCommit": "d105562",
> "GoVersion": "go1.25.4",
> "KernelVersion": "6.8.0-71-generic",
> "MinAPIVersion": "1.44",
> "Os": "linux"
> }
> }
> ...
> }
> 
> 
> \### Expected behavior
> 
> Instead of "APIVersion" the key "ApiVersion" is used in the "Server" block, like with previous versions. 
> 
> \### docker version
> 
> \`\`\`bash
> Client: Docker Engine - Community
> Version: 29.0.0
> API version: 1.52
> Go version: go1.25.4
> Git commit: 3d4129b
> Built: Mon Nov 10 21:46:31 2025
> OS/Arch: linux/amd64
> Context: default
> 
> Server: Docker Engine - Community
> Engine:
> Version: 29.0.0
> API version: 1.52 (minimum version 1.44)
> Go version: go1.25.4
> Git commit: d105562
> Built: Mon Nov 10 21:46:31 2025
> OS/Arch: linux/amd64
> Experimental: false
> containerd:
> Version: v2.1.5
> GitCommit: fcd43222d6b07379a4be9786bda52438f0dd16a1
> runc:
> Version: 1.3.3
> GitCommit: v1.3.3-0-gd842d771
> docker-init:
> Version: 0.19.0
> GitCommit: de40ad0
> \`\`\`
> 
> \### docker info
> 
> \`\`\`bash
> not relevant
> \`\`\`
> 
> \### Additional Info
> 
> \_No response\_

I managed to create a duplicate of an existing issue:

> <https://github.com/moby/moby/issues/51476>
>
> \### Description
> 
> This PR: https://github.com/moby/moby/pull/51233 introduced a n…ew \`ServerVersionResult\` struct used by the client.
> 
> However, this struct does not contain marshaling JSON tags as in e.g. VersionResponse from system https://github.com/moby/moby/blob/master/api/types/system/version\_response.go.
> 
> This causes inconsistencies with the previous docker version 28.x, in particular, the returned marshalled API version is now \`APIVersion\` where it previously was \`ApiVersion\`. This broke downstream code expecting the correct case.
> 
> 
> \### Reproduce
> 
> 1. Update to docker 29.0.0
> 2. Run \`docker version --format "{{ json . }}"\` the \`Server\` entry returns \`APIVersion\` with an incorrect case.
> 
> \### Expected behavior
> 
> \`docker version --format "{{ json . }}"\` should return \`ApiVersion\` in the \`Server\` struct.
> 
> \### docker version
> 
> \`\`\`bash
> Client: Docker Engine - Community
> Version: 29.0.0
> API version: 1.52
> Go version: go1.25.4
> Git commit: 3d4129b
> Built: Mon Nov 10 21:46:03 2025
> OS/Arch: linux/amd64
> Context: default
> 
> Server: Docker Engine - Community
> Engine:
> Version: 29.0.0
> API version: 1.52 (minimum version 1.44)
> Go version: go1.25.4
> Git commit: d105562
> Built: Mon Nov 10 21:46:03 2025
> OS/Arch: linux/amd64
> Experimental: false
> containerd:
> Version: v2.1.5
> GitCommit: fcd43222d6b07379a4be9786bda52438f0dd16a1
> runc:
> Version: 1.3.3
> GitCommit: v1.3.3-0-gd842d771
> docker-init:
> Version: 0.19.0
> GitCommit: de40ad0
> \`\`\`
> 
> \### docker info
> 
> \`\`\`bash
> Client: Docker Engine - Community
> Version: 29.0.0
> Context: default
> Debug Mode: false
> Plugins:
> buildx: Docker Buildx (Docker Inc.)
> Version: v0.29.1
> Path: /usr/libexec/docker/cli-plugins/docker-buildx
> compose: Docker Compose (Docker Inc.)
> Version: v2.40.3
> Path: /usr/libexec/docker/cli-plugins/docker-compose
> 
> Server:
> Containers: 9
> Running: 7
> Paused: 0
> Stopped: 2
> Images: 7
> Server Version: 29.0.0
> Storage Driver: overlay2
> Backing Filesystem: extfs
> Supports d\_type: true
> Using metacopy: false
> Native Overlay Diff: true
> userxattr: false
> Logging Driver: journald
> Cgroup Driver: systemd
> Cgroup Version: 2
> Plugins:
> Volume: local
> Network: bridge host ipvlan macvlan null overlay
> Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
> CDI spec directories:
> /etc/cdi
> /var/run/cdi
> Swarm: active
> NodeID: 2wktmea4icnsrva73jv7o4i3h
> Is Manager: true
> ClusterID: 6980ljqoaq2zmu588lbvopicr
> Managers: 1
> Nodes: 1
> Default Address Pool: 10.0.0.0/16  
> SubnetSize: 24
> Data Path Port: 4789
> Orchestration:
> Task History Retention Limit: 5
> Raft:
> Snapshot Interval: 10000
> Number of Old Snapshots to Retain: 0
> Heartbeat Tick: 1
> Election Tick: 10
> Dispatcher:
> Heartbeat Period: 5 seconds
> CA Configuration:
> Expiry Duration: 3 months
> Force Rotate: 0
> Autolock Managers: false
> Root Rotation In Progress: false
> Node Address: 10.17.2.15
> Manager Addresses:
> 10.17.2.15:2377
> Runtimes: io.containerd.runc.v2 runc
> Default Runtime: runc
> Init Binary: docker-init
> containerd version: fcd43222d6b07379a4be9786bda52438f0dd16a1
> runc version: v1.3.3-0-gd842d771
> init version: de40ad0
> Security Options:
> apparmor
> seccomp
> Profile: builtin
> cgroupns
> no-new-privileges
> Kernel Version: 5.15.0-161-generic
> Operating System: Ubuntu 22.04.5 LTS
> OSType: linux
> Architecture: x86\_64
> CPUs: 1
> Total Memory: 3.82GiB
> Name: sirius2-turquoise-dev-a
> ID: 45e131f1-cd3d-436e-b6df-9bd24f0abdcb
> Docker Root Dir: /data/docker
> Debug Mode: false
> Experimental: false
> Insecure Registries:
> ::1/128
> 127.0.0.0/8
> Live Restore Enabled: false
> Firewall Backend: iptables
> \`\`\`
> 
> \### Additional Info
> 
> \_No response\_

---

<div class="post-metadata">

**Author:** ![meyay](https://sea3.discourse-cdn.com/docker/user_avatar/forums.docker.com/meyay/32/34000_2.png) [@meyay](https://forums.docker.com/u/meyay)\
**Post date:** [November 15, 2025, 12:36pm UTC](https://forums.docker.com/t/breaking-key-change-in-docker-cli-version-response/150390/4 "2025-11-15T12:36:44Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![system](https://global.discourse-cdn.com/docker/original/3X/d/4/d4fbccd46c81bfcffe9822e20e17736d946fa821.png) [@system](https://forums.docker.com/u/system)\
**Post date:** [December 15, 2025, 12:36pm UTC](https://forums.docker.com/t/breaking-key-change-in-docker-cli-version-response/150390/5 "2025-12-15T12:36:57Z")

</div>

Closed on December 15, 2025, 12:36pm UTC

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.