## 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
```text
buildkit secret mount failed on remote builder
```

## Steps
1. Inspect the builder: run `docker buildx inspect` on the builder in use and check the driver and BuildKit version. Expected: you know whether the remote endpoint actually runs a recent BuildKit.
2. Pass the secret at build time: add the `--secret` flag with an id and source to the build command, matching the `id` in the Dockerfile's `--mount=type=secret,id=` clause. Expected: the IDs match exactly.
3. 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.
4. As a fallback, run the build locally (where your Docker has BuildKit) with the same `--secret` flag to isolate builder versus Dockerfile issues. Expected: the local build succeeds, proving the Dockerfile side is fine.
5. 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 build` fails on `--mount=type=secret` against 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; `--secret` flag 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/pst_dcrAdbl41CAWyh85wq_p-Q