# Docker BuildKit "failed to fetch oauth token" - Fix Auth During Build Pull

> Fix BuildKit "failed to solve: failed to fetch oauth token: unexpected status: 401/403" in CI - the build could not authenticate to pull a private base image.

Source: https://latchkey.dev/learn/docker/docker-failed-to-fetch-oauth-token-build  
Updated: 2026-06-25

During the build, BuildKit tried to pull a base image from a private registry and the registry’s token exchange failed. The build cannot authenticate to fetch the `FROM` image.

## Diagnose it: build context, cache, or platform?

A Dockerfile that builds locally and fails in CI usually differs in one of three ways: the build context contains different files, the layer cache is cold or poisoned, or the runner architecture does not match what the base image provides.

```Terminal
# what is actually being sent as build context (dockerignore applies)
docker build --no-cache --progress=plain -t probe . 2>&1 | head -40

# what platform are you on, and what does the base image support?
docker version --format '{{.Server.Arch}}'
docker buildx imagetools inspect <base-image> | grep -i platform

# prove it is not a cache artefact
docker build --no-cache .
```

> `--progress=plain` prints full step output instead of the collapsed TTY view. On a runner the collapsed view hides the line that actually failed, which is why the CI log often looks less informative than your local run.

## Keep the build context small and deterministic

- A missing `.dockerignore` sends `node_modules`, `.git`, and build output to the daemon, which is slow and can change layer hashes between environments.
- A `COPY` of a path that exists locally but is gitignored will fail in CI, because the runner only has what the checkout produced.
- Multi-arch builds need `buildx` and QEMU set up explicitly; a plain `docker build` on an ARM runner silently produces an ARM image.

## FAQ

### What causes Docker BuildKit "failed to fetch oauth token"?

There are 3 common causes: no registry login available to the build, credentials lack scope for the base image repo, and expired short-lived token before the build pulled. The base image is private but the builder has no credentials - docker login was not run, or buildx runs in a context that does not see the login.

### How do I fix Docker BuildKit "failed to fetch oauth token"?

There are 2 fixes depending on which cause you have: log in before building, with read scope for the base and pass credentials to the buildx builder. Work through them in order, since the first is the most common.

### What does Docker BuildKit "failed to fetch oauth token" actually mean?

A docker build/buildx build fails at the FROM (or a --from) pull with failed to fetch oauth token: unexpected status: 401 Unauthorized.

### How do I stop Docker BuildKit "failed to fetch oauth token" happening again?

Authenticate to every private registry the build pulls from, before building. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt