ErrorVaultHQ

Solved Error

How to Fix Docker Error: 'failed to compute cache key: failed to fetch oauth token'

Quick Fix

Log out and back in to Docker Hub, then retry the build: 1. Run docker logout 2. Run docker login and enter your Docker Hub credentials (or a personal access token) 3. Retry your build: docker build . or docker compose up --build If that does not work, restart Docker Desktop completely and try again — this clears a stuck internal DNS/proxy state that commonly causes this exact error.

What this error means

This error comes from BuildKit (Docker's build engine) while it tries to pull a base image like FROM node:20-alpine or FROM alpine:3.21. Before pulling, Docker must get a short-lived OAuth token from auth.docker.io. When that token request fails, you get failed to compute cache key: failed to fetch oauth token. There are several distinct root causes. Check the full error text under the summary line (run with docker build --progress=plain . if you only saw the short version) to identify which one matches.

Step-by-Step Guide

Cause 1: DNS/network failure reaching auth.docker.io

  1. 1Restart Docker Desktop. If your full error mentions dial tcp: lookup auth.docker.io, i/o timeout, no such host, or connection reset by peer, Docker's internal DNS cannot resolve or reach Docker Hub's auth server. This is very common on Windows/Mac with Docker Desktop and WSL2, VPNs, or corporate networks. Fully quit it (not just close the window) and reopen it. Many users report this clears the issue on its own.
  2. 2Disable VPN temporarily. VPNs frequently break Docker Desktop's internal DNS routing to auth.docker.io. Disconnect the VPN and retry the build.
  3. 3Change Docker's DNS settings (Windows/Mac). Open Docker Desktop Settings > Docker Engine and add a dns array pointing to a public resolver, e.g. "dns": ["8.8.8.8", "1.1.1.1"], then apply and restart.
  4. 4Test connectivity manually. Run nslookup auth.docker.io and curl -I https://registry-1.docker.io/v2/ from the same machine/terminal to confirm whether the network path is actually blocked.
  5. 5Restart your machine's networking. On Windows, resetting WSL with wsl --shutdown then restarting Docker Desktop has fixed this for some users.

Cause 2: 401 Unauthorized / Docker Hub pull rate limit

  1. 1Log in to Docker Hub. If the full error says unexpected status from GET request ... 401 Unauthorized or mentions toomanyrequests, this is an authentication or rate-limit issue, not a network outage. Check if you're logged in with docker info | grep Username, then run docker login, and verify with docker pull hello-world.
  2. 2Check for rate limiting. Anonymous users are limited to 100 pulls per 6 hours, and authenticated free users are limited to 200 pulls per 6 hours, with anonymous limits enforced per IP address. If you are on a shared network (office, university, CI runner), you may be sharing that limit with many other people.
  3. 3Authenticate to raise your limit. Private registries require authentication, and authenticated pulls can also help with Docker Hub rate limits. Logging in with a free Docker Hub account roughly doubles your pull allowance.
  4. 4Wait out the window if already rate-limited. The limit resets on a 6-hour rolling/fixed window, so retrying later without changes can also resolve it.
  5. 5Try logging out then back in if login itself seems broken. Some Docker Desktop users found the token error only cleared after fully logging out of Docker Desktop and logging back in, even though nothing else changed.

Cause 3: Corporate proxy, firewall, or GFW (China) blocking the token endpoint

  1. 1Set proxy env vars for the buildx builder specifically. If you are behind a corporate proxy, restrictive firewall, or in a region where Docker Hub is blocked, and especially if you use docker buildx with the docker-container driver, the build container may not inherit your proxy settings even though your host does. When using docker buildx create --driver=docker-container, pass proxy variables explicitly with --driver-opt env.http_proxy=... --driver-opt env.https_proxy=..., since the container does not automatically inherit your shell's http_proxy/https_proxy.
  2. 2Configure Docker Desktop's built-in proxy settings. Go to Settings > Resources > Proxies and set your manual proxy there so the daemon itself uses it for all pulls.
  3. 3Or configure via daemon.json. Add a proxies block to /etc/docker/daemon.json (Linux) with http-proxy, https-proxy, and no-proxy keys, then restart the Docker service.
  4. 4Verify the proxy actually reaches Docker Hub. Run curl -I https://registry-1.docker.io/v2/ through the same proxy to confirm it is not itself blocking Docker Hub traffic.

Cause 4: Private/self-hosted registry misconfiguration

  1. 1Log in to your private registry. If the registry in the error is your own company registry (not docker.io) and you see authorization server did not include a token in the response, the problem is on the registry/auth-server side, not your machine. Confirm you are logged in to that specific registry with docker login your-registry.example.com, not just Docker Hub.
  2. 2Check the registry's auth service configuration. This error typically means the registry's token auth server returned a malformed or empty response — a server-side or reverse-proxy header stripping issue that needs fixing by whoever administers that registry.
  3. 3Report the server-side issue to your team. Escalate to your platform/DevOps team if you don't control the registry, since this is a server-side bug rather than something fixable from the client.

Fix 5: Restart Docker Desktop

  1. 1Restart Docker Desktop (or the Docker daemon on Linux with sudo systemctl restart docker).

Fix 6: Update Docker Desktop / Docker Engine

  1. 1Update Docker Desktop / Docker Engine to the latest version, since some token-fetch bugs were fixed in later BuildKit/buildx releases.

Fix 7: Clear build cache

  1. 1Clear build cache with docker builder prune -a and retry.

Fix 8: Try pulling the base image directly

  1. 1Try pulling the base image directly with docker pull <image> outside of a build — if that also fails with the same oauth error, the problem is confirmed to be network/auth, not your Dockerfile.

When to get further help

If none of the above works, gather the full error output using docker build --progress=plain --no-cache . and share it on the Docker Community Forums or your registry provider's support channel — the exact wording after 'failed to fetch oauth token' (timeout, 401, connection reset, or malformed response) is the key detail needed to pinpoint the cause.

Sources:

Heads up: this guide was drafted with AI assistance from the real sources listed below, and structured by our team for clarity. It may not cover every possible cause — if it doesn't fix your issue, let us know and we'll take a closer look. See how we create our fixes.

Was this fix helpful?

Related Error Fixes