🚨 Docker Error Guide: 'image operating system "linux" cannot be used on this platform' — OS/Arch Mismatch

Overview

Docker refuses to run or pull an image when the image’s declared operating system or CPU architecture does not match what the local daemon can execute. The message appears during docker pull, docker run, or docker create:

image operating system "linux" cannot be used on this platform: 'windows'

You will also see the architecture variant when a Linux daemon is fed an image built for a different CPU:

image operating system "linux" cannot be used on this platform
no matching manifest for windows/amd64 in the manifest list entries

The error is a platform-compatibility check, not a corruption or network problem. Docker is telling you the image was built for a different OS or architecture than the engine you are running.

Symptoms

• docker run or docker pull aborts immediately with cannot be used on this platform.
• A Windows container host cannot pull a linux/* image, or a Linux host cannot pull a windows/* image.
• On Docker Desktop for Windows, switching between Linux and Windows container modes changes whether the pull succeeds.
• On Apple Silicon (arm64) or Raspberry Pi, an amd64-only image fails with a platform or no matching manifest message.
• docker image inspect shows an Os or Architecture value that differs from your host.

Common Root Causes

• Container mode mismatch on Windows — Docker Desktop is set to Windows containers but the image is a Linux image (or vice versa).
• CPU architecture mismatch — pulling an amd64 image on an arm64 host, or an arm64 image on amd64, when no matching manifest exists.
• Single-arch image with no manifest list — the repository publishes only one platform, so there is no variant Docker can select for your host.
• --platform forced incorrectly — a build or run pinned --platform=windows/amd64 (or the wrong arch) that the host cannot honor.
• Base image OS baked into a Dockerfile — a FROM mcr.microsoft.com/windows/... image used on a Linux daemon.
• Multi-arch build missing your target — a CI docker buildx step never emitted the platform your host needs.

Diagnostic Workflow

First, confirm what OS and architecture your daemon actually runs:

docker version --format 'Server: {{.Server.Os}}/{{.Server.Arch}}'
docker info --format 'OSType={{.OSType}} Arch={{.Architecture}}'

Inspect the image’s declared platform. If it does not match the line above, that is the mismatch:

docker image inspect myapp:1.4.2 --format '{{.Os}}/{{.Architecture}}'

Check the remote manifest list to see every platform the tag actually publishes:

docker manifest inspect registry.example.com/myapp:1.4.2 \
  | grep -A2 platform

If you are on Docker Desktop for Windows, verify the container mode. Right-click the Docker tray icon and read “Switch to Linux containers…” / “Switch to Windows containers…” — the option shown is the mode you are not in.

Try an explicit platform pull to confirm which variants resolve:

docker pull --platform linux/arm64 registry.example.com/myapp:1.4.2
docker pull --platform linux/amd64 registry.example.com/myapp:1.4.2

Example Root Cause Analysis

A developer on an Apple Silicon MacBook runs docker run registry.example.com/myapp:1.4.2 and gets image operating system "linux" cannot be used on this platform followed by no matching manifest for linux/arm64. Their daemon reports linux/arm64:

docker info --format 'OSType={{.OSType}} Arch={{.Architecture}}'
# OSType=linux Arch=aarch64

Inspecting the remote manifest shows only one entry, linux/amd64 — the CI pipeline built a single-arch image. Because there is no arm64 variant, the daemon cannot select a compatible image. Two fixes apply: run the amd64 image under emulation, or publish a real arm64 build.

Immediate workaround using QEMU emulation:

docker run --platform linux/amd64 registry.example.com/myapp:1.4.2

Permanent fix — publish a multi-arch image from CI with buildx:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/myapp:1.4.2 --push .

After the multi-arch push, docker manifest inspect lists both platforms and the arm64 host pulls the native variant with no emulation.

Prevention Best Practices

• Build multi-arch images in CI with docker buildx build --platform linux/amd64,linux/arm64 so every host pulls a native variant.
• Standardize your Dockerfiles and validate them before publishing — the Dockerfile validator catches base images and platform assumptions early.
• Document which container mode a Windows image requires and keep Linux and Windows images in clearly separated tags or repositories.
• Avoid forcing --platform in run commands unless you specifically intend emulation; let Docker select the native match.
• On mixed fleets, add a CI check that runs docker manifest inspect and fails if a required platform is missing.
• Reserve emulation (--platform cross-arch runs) for local testing only; it is slower and can mask arch-specific bugs.

Quick Command Reference

# Host OS/architecture
docker info --format 'OSType={{.OSType}} Arch={{.Architecture}}'

# Image's declared platform
docker image inspect myapp:1.4.2 --format '{{.Os}}/{{.Architecture}}'

# Every platform a tag publishes
docker manifest inspect registry.example.com/myapp:1.4.2

# Force a specific platform (emulation)
docker run --platform linux/amd64 registry.example.com/myapp:1.4.2

# Build and push multi-arch
docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.example.com/myapp:1.4.2 --push .

Conclusion

image operating system "linux" cannot be used on this platform is Docker enforcing a hard compatibility boundary: an image built for one OS or CPU architecture cannot run on a daemon that targets another. Confirm your host’s OSType/Architecture, inspect the image’s declared Os/Architecture, and check the remote manifest for a matching variant. The durable fix is publishing multi-arch images so every host in your fleet — amd64, arm64, Linux, or Windows — pulls a native build. For more runtime and build fixes, see the Docker guides.