Incorrect TARGETPLATFORM and platform in registry when build --platform is specified by FROM statement in the Dockerfile

[miki725]

Contributing guidelines and issue reporting guide

• I've read the contributing guidelines and wholeheartedly agree. I've also read the issue reporting guide.

Well-formed report checklist

• I have found a bug that the documentation does not mention anything about my problem
• I have found a bug that there are no open or closed issues that are related to my problem
• I have provided version/information about my environment and done my best to provide a reproducer

Description of bug

Bug description

When you specify a --platform in the Dockerfile that does not match the host runner platform, the override is not propagated to:

• TARGETPLATFORM arg
• pushed manifest list platform os/arch property

For example my host runner is amd64:

➜ uname -a
Linux earth 6.18.7-arch1-1 #1 SMP PREEMPT_DYNAMIC Sat, 24 Jan 2026 00:47:39 +0000 x86_64 GNU/Linux

but when you build an arm64 image:

$ echo '
FROM --platform=linux/arm64 alpine
ARG BUILDPLATFORM
ARG TARGETPLATFORM
RUN set -x && uname -a && env | grep PLATFORM
' | docker buildx build -f - . -t 10.10.20.30:5044/arm --push --no-cache --progress=plain

...

#5 [2/2] RUN set -x && uname -a && env | grep PLATFORM
#5 0.060 + uname -a
#5 0.072 Linux buildkitsandbox 6.18.7-arch1-1 #1 SMP PREEMPT_DYNAMIC Sat, 24 Jan 2026 00:47:39 +0000 aarch64 Linux
#5 0.075 + env
#5 0.076 + grep PLATFORM
#5 0.091 BUILDPLATFORM=linux/amd64
#5 0.092 TARGETPLATFORM=linux/amd64
#5 DONE 0.1s

...

#6 exporting config sha256:3129b921ca4b16c081b12b423fdedffea6e4f17b78531937a886a8e0dcccec5f done
#6 exporting manifest list sha256:60d6f9b5f25165b45b667dcbd9608e51a99fe0730048c2791ed8741b22fb41c2 done

note:

• uname reports aarch64 build so the runtime of the container is definitely arm64 as expected
• TARGETPLATFORM is still linux/amd64 which is not expected

In addition if the pushed image is inspected in the registry:

➜ docker buildx imagetools inspect --raw localhost:5044/arm:latest@sha256:60d6f9b5f25165b45b667dcbd9608e51a99fe0730048c2791ed8741b22fb41c2
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:85d5ffcb8bdafe9be72ff2d5d5cca3d6a8ed253882eb15ea979c5e972ae1a3a5",
      "size": 668,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:c56dd93f794bd95598119461ec062efafbe0780fa410049a6c7b0fd62f0a78a5",
      "size": 566,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:85d5ffcb8bdafe9be72ff2d5d5cca3d6a8ed253882eb15ea979c5e972ae1a3a5",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    }
  ]
}

The reported platform is amd64 which is wrong. That can be confirmed by inspecting the pushed image config object which shows arm64 as expected:

➜ docker buildx imagetools inspect --raw 10.10.20.30:5044/arm:latest@sha256:3129b921ca4b16c081b12b423fdedffea6e4f17b78531937a886a8e0dcccec5f | jq '{os, architecture}'
{
  "os": "linux",
  "architecture": "arm64"
}

Further this discrepancy is confirmed by attempting to pull the image with specific --platform:

➜ docker pull localhost:5044/arm --platform=linux/arm64
Using default tag: latest
latest: Pulling from arm
no matching manifest for linux/arm64 in the manifest list entries

But pulling the image without --platform and then checking its config arch confirms its actually an arm64 image:

➜ docker pull localhost:5044/arm
...
Using default tag: latest
Digest: sha256:60d6f9b5f25165b45b667dcbd9608e51a99fe0730048c2791ed8741b22fb41c2
Status: Downloaded newer image for localhost:5044/arm:latest

➜ docker run -it --rm localhost:5044/arm uname -m
aarch64

Related issues

I found very similar #5677 but there are some diffs:

• this is reproducible with a single architecture build (not multi-platform)
• TARGETPLATFORM is incorrect
• platform pushed in manifest list is wrong

Reproduction

See above.

Version information

➜ uname -a
Linux earth 6.18.7-arch1-1 #1 SMP PREEMPT_DYNAMIC Sat, 24 Jan 2026 00:47:39 +0000 x86_64 GNU/Linux


➜ docker version
Client:
 Version:           29.2.1
 API version:       1.53
 Go version:        go1.25.6 X:nodwarf5
 Git commit:        a5c7197d72
 Built:             Thu Feb  5 10:59:55 2026
 OS/Arch:           linux/amd64
 Context:           default

Server:
 Engine:
  Version:          29.2.1
  API version:      1.53 (minimum version 1.44)
  Go version:       go1.25.6 X:nodwarf5
  Git commit:       6bc6209b88
  Built:            Thu Feb  5 10:59:55 2026
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v2.2.1
  GitCommit:        dea7da592f5d1d2b7755e3a161be07f43fad8f75.m
 runc:
  Version:          1.4.0
  GitCommit:
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0


➜ docker buildx version
github.com/docker/buildx 0.31.0 44945d71ff077ce7fc142fbdee6acec8d9acb630


➜ docker info
Client:
 Version:    29.2.1
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  0.31.0
    Path:     /usr/lib/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  5.0.2
    Path:     /usr/lib/docker/cli-plugins/docker-compose

Server:
 Containers: 13
  Running: 13
  Paused: 0
  Stopped: 0
 Images: 420
 Server Version: 29.2.1
 Storage Driver: overlay2
  Backing Filesystem: btrfs
  Supports d_type: true
  Using metacopy: true
  Native Overlay Diff: false
  userxattr: false
 Logging Driver: json-file
 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: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: dea7da592f5d1d2b7755e3a161be07f43fad8f75.m
 runc version:
 init version: de40ad0
 Security Options:
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.18.7-arch1-1
 Operating System: Arch Linux
 OSType: linux
 Architecture: x86_64
 CPUs: 12
 Total Memory: 62.51GiB
 Name: earth
 ID: 2de7fd2d-9d55-4cd8-a4dd-c5c3d39714f0
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Username: crashappsec
 Experimental: false
 Insecure Registries:
  localhost:5044
  ::1/128
  127.0.0.0/8
 Live Restore Enabled: false
 Firewall Backend: iptables

[tonistiigi]

TARGETPLATFORM is the platform you set with build command build --platform=, it is not the the platform you set for the FROM --platform pull specific platform image for a stage. TARGETPLATFORM and BUILDPLATFORM not matching is the foundation what makes cross-compilation in Dockerfiles possible.

[miki725]

sure TARGETPLATFORM and BUILDPLATFORM dont need to match. the issue is that its the wrong value:

• the TARGETPLATFORM should match the arch of whats actually building, no?
• likewise the platform pushed to the registry should match what was actually built

neither is true if you specify --platform in the FROM statement as described in the issue

[tonistiigi]

TARGETPLATFORM matches the value user passed as build --platform (if they didn't pass then host default).

This does not mean that you can not run commands/stages for other platforms than what the user passed in your Dockerfile.

FROM --platform does not switch TARGETPLATFORM. The default value for --platform in FROM is --platform=$TARGETPLATFORM so the only reason to ever set this flag is if you want the commands in the stage to be from a different platform than what the user requested, for example if you are running a cross-compiler in this stage.

[miki725]

If thats expected behavior for TARGETPLATFORM, sure. I thought its meant to indicate what is actually building.

The value for platform pushed to the registry seems wrong though to me. The platform from docker inspect should match whatever is in the manifest list which currently it does not.

In the example above docker inspect will show arm64 whereas in the manifest list it shows up as amd64. As such docker pull --platform=linux/arm64 fails which is not expected.

Whatever is pushed to the registry by docker is the final product of the build (ignoring build cache, etc). It should not matter whether the user supplied the platform in the CLI flag or in the FROM statement. The manifest list should reflect the runtime of the actual image, if you download it, and decide to run it.

As-is, if someone else attempts to download that "amd64" image and their docker runtime doesnt support arm64 via QEMU, it wont be able to run it. Note that it gets even worse in cloud environments such as AWS ECS where user does not control how the provider picks which architecture it downloads. I would imagine it goes by the platform in the manifest list as its source of truth.

[tonistiigi]

whether the user supplied the platform in the CLI flag or in the FROM statement.

These are not the same thing. Only the CLI flag is for setting the platform of the build. FROM flag is for setting platform for the commands in a Dockerfile stage(setting platform for pulling the base image for that stage that most likely contains binaries for specific architecture). You would only set it if you are doing something advanced where you want to run commands for a specific architecture. You are not supposed to return the stage with binaries for this different architecture(that doesn't match TARGETPLATFORM) as a build result.