[BUG] docker compose ignores local non-native variant from a multi-platform image (pulls instead)

[skrysm]

Description

Disclaimer: This bug report was created with AI (due to me having very little time for these kind of things). The problem, however, is very real. I have been trying to figure it out for the last couple of day and this bug report is the result of the analysis.

When Docker's containerd image store is enabled and a locally tagged multi-platform image contains both the host platform and a non-native platform, Docker Compose incorrectly treats the image as unavailable for the non-native platform and attempts to pull it from a registry.

In this reproduction, the Docker host is linux/arm64, while the Compose service requests linux/amd64. The unpublished local image tag contains runnable variants for both platforms.

Current behavior:

• docker image inspect --platform linux/amd64 finds the requested local variant.
• docker run --platform linux/amd64 runs the local variant successfully.
• docker compose up reports that the local image does not match linux/amd64, treats it as missing, and attempts to pull the unpublished tag (which fails).
• docker compose up --pull never runs the same local linux/amd64 variant successfully.

Expected behavior:

With the default missing pull policy, Compose should recognize that the requested linux/amd64 variant is available in the local multi-platform image and start it without contacting a registry.

Steps To Reproduce

Disclaimer: These instructions were generated by AI. I have manually verified them.

These steps use an ARM64 Docker host (macOS in my case) and Docker's containerd image store. Docker Desktop provides the emulation needed to run the non-native AMD64 variant. On an AMD64 host, the requested and host platforms can be reversed if ARM64 emulation is available.

1. Confirm that the containerd image store is enabled:

   docker info --format '{{json .DriverStatus}}'

   The output should contain:

   io.containerd.snapshotter.v1
   

2. Pull the ARM64 and AMD64 variants of Alpine into the local multi-platform image store, then give the image a tag that does not exist in the registry:

   docker pull --platform linux/arm64 alpine:3.22
   docker pull --platform linux/amd64 alpine:3.22
   docker tag alpine:3.22 docker.io/library/compose-multiplatform-repro-codex:local-only

3. Confirm that both variants are locally available:

   docker image ls --tree docker.io/library/compose-multiplatform-repro-codex:local-only

   The output includes locally stored content for both requested platforms:

   IMAGE                                          ID             DISK USAGE   CONTENT SIZE   EXTRA
   compose-multiplatform-repro-codex:local-only   14358309a308       26.2MB         8.08MB
   ├─ linux/amd64                                 7c8cb692ae09       12.7MB         3.79MB
   ├─ linux/arm64/v8                              2c9d26f410d0       13.3MB         4.12MB
   

4. Create compose.yaml:

   services:
     repro:
       image: docker.io/library/compose-multiplatform-repro-codex:local-only
       platform: linux/amd64
       command: ["uname", "-m"]

5. Run the requested local variant directly with Docker:

   docker run --rm --platform linux/amd64 docker.io/library/compose-multiplatform-repro-codex:local-only uname -m

   This succeeds:

   x86_64
   

6. Run the equivalent service with Compose and enable debug logging:

   docker --debug compose up --abort-on-container-exit --exit-code-from repro

   Compose incorrectly rejects the local image and attempts to pull it:

   level=debug msg="local image docker.io/library/compose-multiplatform-repro-codex:local-only doesn't match expected platform linux/amd64"
   Image docker.io/library/compose-multiplatform-repro-codex:local-only Pulling
   Image docker.io/library/compose-multiplatform-repro-codex:local-only Error pull access denied for compose-multiplatform-repro-codex, repository does not exist or may require 'docker login'
   Error response from daemon: pull access denied for compose-multiplatform-repro-codex, repository does not exist or may require 'docker login'
   

7. Disable pulling and run the same Compose service:

   docker compose up --pull never --abort-on-container-exit --exit-code-from repro

   This succeeds using the requested local variant:

   repro-1  | x86_64
   repro-1 exited with code 0
   

8. Clean up the reproduction resources:

   docker compose down --remove-orphans
   docker image rm docker.io/library/compose-multiplatform-repro-codex:local-only

Compose Version

$ docker compose version
Docker Compose version v5.3.1

$ docker-compose version
Docker Compose version v5.3.1

Docker Environment

Client:
 Version:    29.6.2
 Context:    desktop-linux
 Debug Mode: false
 Plugins:
  agent: Docker AI Agent Runner (Docker Inc.)
    Version:  v1.115.0
    Path:     /Users/manski/.docker/cli-plugins/docker-agent
  ai: Docker AI Agent - Ask Gordon (Docker Inc.)
    Version:  v1.27.0
    Path:     /Users/manski/.docker/cli-plugins/docker-ai
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.35.0-desktop.2
    Path:     /Users/manski/.docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v5.3.1
    Path:     /Users/manski/.docker/cli-plugins/docker-compose
  debug: Get a shell into any image or container (Docker Inc.)
    Version:  0.0.47
    Path:     /Users/manski/.docker/cli-plugins/docker-debug
  desktop: Docker Desktop commands (Docker Inc.)
    Version:  v0.4.3
    Path:     /Users/manski/.docker/cli-plugins/docker-desktop
  dhi: CLI for managing Docker Hardened Images (Docker Inc.)
    Version:  v0.0.7
    Path:     /Users/manski/.docker/cli-plugins/docker-dhi
  extension: Manages Docker extensions (Docker Inc.)
    Version:  v0.2.31
    Path:     /Users/manski/.docker/cli-plugins/docker-extension
  init: Creates Docker-related starter files for your project (Docker Inc.)
    Version:  v1.4.0
    Path:     /Users/manski/.docker/cli-plugins/docker-init
  mcp: Docker MCP Plugin (Docker Inc.)
    Version:  v0.43.3
    Path:     /Users/manski/.docker/cli-plugins/docker-mcp
  model: Docker Model Runner (Docker Inc.)
    Version:  v1.2.6
    Path:     /Users/manski/.docker/cli-plugins/docker-model
  offload: Docker Offload (Docker Inc.)
    Version:  v0.6.9
    Path:     /Users/manski/.docker/cli-plugins/docker-offload
  pass: Docker Pass Secrets Manager Plugin (beta) (Docker Inc.)
    Version:  v0.2.0
    Path:     /Users/manski/.docker/cli-plugins/docker-pass
  sandbox: "docker sandbox" is deprecated, use Docker Sandboxes instead (Docker Inc.)
    Version:  v0.13.0
    Path:     /Users/manski/.docker/cli-plugins/docker-sandbox
  scout: Docker Scout (Docker Inc.)
    Version:  v1.24.0
    Path:     /Users/manski/.docker/cli-plugins/docker-scout

Server:
 Containers: 1
  Running: 0
  Paused: 0
  Stopped: 1
 Images: 2
 Server Version: 29.6.2
 Storage Driver: overlayfs
  driver-type: io.containerd.snapshotter.v1
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 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
 Discovered Devices:
  cdi: docker.com/gpu=webgpu
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: e53c7c1516c3b2bff98eb76f1f4117477e6f4e66
 runc version: v1.3.6-0-g491b69ba
 init version: de40ad0
 Security Options:
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.12.76-linuxkit
 Operating System: Docker Desktop
 OSType: linux
 Architecture: aarch64
 CPUs: 8
 Total Memory: 3.826GiB
 Name: docker-desktop
 ID: 3eff3bdc-fd0e-4464-bc5d-1cfad3f2db4e
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 HTTP Proxy: http.docker.internal:3128
 HTTPS Proxy: http.docker.internal:3128
 No Proxy: hubproxy.docker.internal
 Labels:
  com.docker.desktop.address=unix:///Users/manski/Library/Containers/com.docker.docker/Data/docker-cli.sock
 Experimental: false
 Insecure Registries:
  hubproxy.docker.internal:5555
  127.0.0.0/8
  ::1/128
 Live Restore Enabled: false
 Firewall Backend: iptables

Anything else?

Disclaimer: This analysis has been done by the AI. I haven't verified it (lack of knowledge), so take it with a grain of salt.

The issue only occurs with Compose's default pull behavior. Both of the following avoid the incorrect registry request and successfully run the requested local variant:

pull_policy: never

docker compose up --pull never

Compose's debug output shows the incorrect local-image decision directly:

local image docker.io/library/compose-multiplatform-repro-codex:local-only doesn't match expected platform linux/amd64

The likely cause is the platform validation in getLocalImagesDigests. It inspects the local image without requesting service.Platform, compares the returned platform with the requested platform, and deletes the image from the local-image map on a mismatch.

With a multi-platform containerd image store, a platformless inspection can return the host variant even though the requested non-native variant is also locally available. Docker supports selecting the variant during inspection with docker image inspect --platform.

The same local-platform check remains in Compose v5.4.0.

Related reports provide historical context but do not appear to cover this exact containerd multi-platform case:

• #9740 led to the local-platform validation, but concerned the classic single-platform image store.
• #11842 concerned a genuinely wrong-platform local image and diagnostic output.
• #12854 concerned multiple platforms under one tag with the classic store; enabling the containerd image store was the recommended solution.

The bug was originally observed in this GitHub Actions job, then reproduced independently with the minimal Alpine example above.