docker build failed: buildkit secret mount error

TL;DR

BuildKit secret mounts need BuildKit enabled, the right Dockerfile syntax line, and the secret passed at build time. The value is available during the build step and never lands in a layer.

Error

docker build failed: buildkit secret mount error

Steps

1. Enable BuildKit for the build. Expected: BuildKit, not the legacy builder, runs.
2. Add the syntax directive at the top of the Dockerfile for the mount flag. Expected: the parser accepts the mount option.
3. Use the mount in the RUN step that needs the secret, reading it from the mounted path. Expected: the step sees the value.
4. Pass the secret at build time with the build secret flag. Expected: the mount is populated.
5. Verify the built image contains no trace: inspect layers and grep. Expected: clean image.

When to use

• Builds needing credentials (private registries, package feeds) without baking them in.
• Fixing secret-mount syntax errors.

When not to use

• Runtime secrets (inject at run, not build).
• Legacy builder (upgrade to BuildKit first).

Tool compatibility

• Docker BuildKit; build secret mounts.

Variant phrasings

buildkit secret not mounted

Flag or syntax issue.

docker build secret mount failed

Same checklist.

Why it happens

Secret mounts are a BuildKit feature with three moving parts (builder, syntax, flag); any one missing breaks the mount.

Edge cases

• The mount is only visible to the RUN step that declares it; other steps cannot see it, by design.
• CI builders need BuildKit enabled too, not just local.
• Secret ids must match between the Dockerfile and the build flag.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0gR1VtKOAFg8E7pHPgJYHw