Docker "secret <id> not found" - Fix RUN --mount=type=secret in CI

A RUN --mount=type=secret,id=X expects a secret named X to be supplied at build time. BuildKit could not find it because no matching --secret id=X,... was passed to the build.

What this error means

The build fails on the secret-mounting RUN step with secret <id> not found. The Dockerfile is fine; the build invocation simply did not provide the secret the mount references.

docker build output

ERROR: failed to solve: secret npmrc not found
# Dockerfile has: RUN --mount=type=secret,id=npmrc ...
# but the build was run without --secret id=npmrc,src=...

Common causes

No --secret passed for the mounted id

The id= in the mount must match a --secret id=... on the build command. A missing or mismatched id leaves the mount unsatisfied.

The secret source file/env is absent in CI

A --secret id=npmrc,src=./.npmrc whose source file was never created on the runner (or --secret id=tok,env=TOKEN with an unset env var) provides nothing to mount.

build-push-action secrets not wired

When using docker/build-push-action, the secrets: input must declare each id; omitting it means the mount has no matching secret.

How to fix it

Pass the secret with a matching id

Supply the secret from a file or env var, using the same id as the mount.

Terminal

# from an env var:
docker build --secret id=npmrc,env=NPMRC .
# or from a file:
docker build --secret id=npmrc,src=$HOME/.npmrc .

Wire secrets in build-push-action

Declare each secret id in the action so the mount resolves.

.github/workflows/build.yml

- uses: docker/build-push-action@v6
  with:
    secrets: |
      npmrc=${{ secrets.NPMRC }}

How to prevent it

Keep mount id= and --secret id= identical and in one place.
Assert the secret source (file or env) exists before building.
Use build secrets, not ARGs, for credentials so they never land in layers.