Docker "FROM --platform invalid" in CI

By Kaveh Alemi·Latchkey

A FROM --platform=os/arch[/variant] line pins the base image platform. A typo (linux/amd instead of linux/amd64), an unknown OS, or a bad variant makes BuildKit reject the platform string before it pulls the base.

What this error means

A build fails on the FROM --platform=... line with invalid platform or unknown operating system or architecture.

ERROR: failed to solve: failed to parse platform linux/amd: unknown operating system or architecture: invalid argument

Common causes

A typo in os/arch

Values like linux/amd, linux/x86_64, or linux/arm (missing the version) are not valid platform identifiers.

An interpolated build arg that is empty or wrong

A FROM --platform=$TARGETPLATFORM where the arg is unset or set to garbage produces an invalid string.

How to fix it

Use a valid platform identifier

1. Use the canonical os/arch form, e.g. linux/amd64, linux/arm64, or linux/arm/v7.

FROM --platform=linux/amd64 golang:1.22 AS build

Rely on the automatic build platform args

1. Prefer $BUILDPLATFORM/$TARGETPLATFORM, which BuildKit fills with valid values.

FROM --platform=$BUILDPLATFORM golang:1.22 AS build
ARG TARGETOS TARGETARCH
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build ./...

How to prevent it

• Use canonical os/arch strings; let BuildKit supply $TARGETPLATFORM.
• Validate any interpolated platform arg before the build.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation