# failed to solve: failed to resolve secret: secret 'npm_token' not found

- **ID:** `docker/secret-not-found-in-build`
- **Domain:** docker
- **Category:** build_error
- **Verification:** ai_generated
- **Fix Rate:** 90%

## Root Cause

Docker BuildKit secret referenced in the Dockerfile via --mount=type=secret is not provided during the build command, or the secret ID does not match.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker 24.0.6 | active | — | — |
| BuildKit 0.12.2 | active | — | — |
| Docker Compose v2.21.0 | active | — | — |
| Node.js 20.0.0 | active | — | — |

## Workarounds

1. **Pass the secret during build: 'DOCKER_BUILDKIT=1 docker build --secret id=npm_token,src=./npm_token.txt -t myapp .'** (90% success)
   ```
   Pass the secret during build: 'DOCKER_BUILDKIT=1 docker build --secret id=npm_token,src=./npm_token.txt -t myapp .'
   ```
2. **Use docker compose with a secrets section in docker-compose.yml: define the secret under 'secrets:' and reference it in the build block with 'secrets: [npm_token]'.** (85% success)
   ```
   Use docker compose with a secrets section in docker-compose.yml: define the secret under 'secrets:' and reference it in the build block with 'secrets: [npm_token]'.
   ```
3. **Verify the secret ID in the Dockerfile matches exactly: check '--mount=type=secret,id=npm_token' and ensure the build command uses '--secret id=npm_token'.** (95% success)
   ```
   Verify the secret ID in the Dockerfile matches exactly: check '--mount=type=secret,id=npm_token' and ensure the build command uses '--secret id=npm_token'.
   ```

## Dead Ends

- **Setting the secret as an environment variable using ENV in Dockerfile** — Secrets are designed to avoid embedding in the image; ENV persists the value in layers. The error persists because the mount still expects a secret source. (85% fail)
- **Adding 'RUN --mount=type=secret,id=npm_token' without the --secret flag in the build command** — The mount declaration alone is insufficient; you must pass the secret from the host using '--secret id=npm_token,src=path' during build. (90% fail)
- **Creating a .env file and using docker compose build** — Compose does not automatically inject .env files as BuildKit secrets; they become build args, not secrets. The secret mount still fails. (70% fail)