## 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

```text
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