buildkit secret mount failed on remote builder
Fixes BuildKit --mount=type=secret failures on remote builders by ensuring the builder supports secret mounts, passing secrets correctly, and falling back to local builds when needed. Not for Dockerfile syntax errors.
TL;DR
RUN --mount=type=secret needs a BuildKit builder that supports secret mounts and the secret passed with --secret at build time. Remote builders on old versions (or non-BuildKit drivers) fail the mount. Upgrade the builder or build locally with the secret flag.
Error
buildkit secret mount failed on remote builderSteps
- Inspect the builder: run
docker buildx inspecton the builder in use and check the driver and BuildKit version. Expected: you know whether the remote endpoint actually runs a recent BuildKit. - Pass the secret at build time: add the
--secretflag with an id and source to the build command, matching theidin the Dockerfile's--mount=type=secret,id=clause. Expected: the IDs match exactly. - Upgrade or replace the builder: create a buildx builder with a current BuildKit version if the remote one is too old to support secret mounts. Expected: the new builder advertises secret-mount support.
- As a fallback, run the build locally (where your Docker has BuildKit) with the same
--secretflag to isolate builder versus Dockerfile issues. Expected: the local build succeeds, proving the Dockerfile side is fine. - Never bake the secret into a layer: confirm the final image history contains no secret material. Expected: the secret was only visible at build time inside the mount.
When to use
docker buildx buildfails on--mount=type=secretagainst a remote builder- CI builds fail while local builds succeed (builder version skew)
- Setting up secret-safe Docker builds
When not to use
- Dockerfile syntax errors in the RUN instruction
- Secrets needed at runtime (use runtime secret injection instead)
Tool compatibility
- Docker BuildKit, buildx builders;
--secretflag and--mount=type=secret
Variant phrasings
docker buildx secret mount not supported
The remote builder's BuildKit is too old; point buildx at a current builder.
buildkit mount secret id mismatch
The --secret id= value must equal the mount's id=; a mismatch fails the mount.
Why it happens
Build secrets are a BuildKit feature negotiated between the client and the builder. Older or non-BuildKit remote builders do not implement the mount type, and the client only sends secrets explicitly flagged with --secret, so a missing flag or an old builder both fail the same way.
Provenance
Resolved from the public thread: https://vectle.com/posts/pstdcrAdbl41CAWyh85wqp-Q