🐳 Docker Error Guide: 'failed to solve: rpc error code = Unknown' BuildKit Failure

Exact Error Message

------
 > [internal] load metadata for docker.io/library/node:20:
------
ERROR: failed to solve: rpc error: code = Unknown desc = failed to fetch anonymous token:
unexpected status from GET request to https://auth.docker.io/token: 429 Too Many Requests

The wrapper is always the same; the desc = tail carries the real reason. Other common tails include:

ERROR: failed to solve: rpc error: code = Unknown desc = failed to solve with frontend dockerfile.v0:
failed to create LLB definition: Dockerfile parse error on line 12: unknown instruction: RUNN

What It Means

Modern docker build runs on BuildKit, a client/daemon architecture that talks over gRPC. The build “frontend” (usually dockerfile.v0) parses your Dockerfile into a build graph (LLB) and the BuildKit backend “solves” it. When any step in that pipeline fails, BuildKit surfaces the failure as a gRPC status: rpc error: code = Unknown desc = <real message>.

So rpc error: code = Unknown is not itself the problem. It is the transport wrapper. The text after desc = is the actual error, whether that is a registry rate limit, a Dockerfile syntax mistake, a network timeout fetching metadata, or a builder that has run out of disk. Read that tail first.

Common Causes

• Docker Hub rate limiting on anonymous pulls (429 Too Many Requests fetching a token).
• A Dockerfile syntax error the frontend cannot parse (unknown instruction, parse error).
• Network failure resolving or pulling a base image (failed to fetch, dial tcp: i/o timeout).
• The BuildKit builder ran out of disk or has a corrupted cache.
• A # syntax= directive pointing at a frontend image that cannot be pulled.
• A stale or crashed buildx builder instance.

Diagnostic Commands

Re-run the build with full progress so the real desc and the failing step are visible:

docker build --progress=plain -t myapp:latest .

List your buildx builders and check their state:

docker buildx ls

Inspect the active builder and its backing driver:

docker buildx inspect --bootstrap

Check daemon disk pressure, a frequent hidden cause of Unknown solve failures:

docker system df

Confirm you can reach the registry and pull the base image directly:

docker pull node:20

Step-by-Step Resolution

1. Read the desc = text and treat it as the actual error. A 429 is rate limiting; unknown instruction is a typo; i/o timeout is network. Fix that specific cause rather than the gRPC wrapper.

2. For Docker Hub 429 rate limits, authenticate so you get a higher pull quota, or mirror the base image:

docker login
docker build -t myapp:latest .

3. For parse errors, re-read the cited line. Fix the malformed instruction, then rebuild. Pin the frontend explicitly if you rely on newer syntax:

# syntax=docker/dockerfile:1
FROM node:20

4. Clear a corrupted or full build cache, which resolves many transient Unknown solves:

docker builder prune -f
docker system prune -f

5. Recreate the buildx builder if it is stuck or crashed:

docker buildx rm mybuilder 2>/dev/null
docker buildx create --name mybuilder --use --bootstrap

6. As a last resort to isolate BuildKit-specific behavior, build with the legacy builder to compare:

DOCKER_BUILDKIT=0 docker build -t myapp:latest .

7. Re-run the BuildKit build and confirm it completes:

docker build --progress=plain -t myapp:latest .

 => => naming to docker.io/library/myapp:latest
 => => exporting layers

Prevention

• Authenticate to Docker Hub (or use a pull-through registry mirror) so builds are not throttled by anonymous rate limits.
• Pin the frontend with # syntax=docker/dockerfile:1 for stable, well-defined parsing.
• Keep build hosts from filling up; schedule docker builder prune and monitor docker system df.
• Always debug with --progress=plain; the default auto progress hides the very desc = line you need.
• Cache base images in CI to avoid network flakiness during load metadata steps. For generating tidy multi-stage Dockerfiles that parse cleanly, try the DevOps AI prompt library.

Related Errors

• failed to solve with frontend dockerfile.v0: failed to create LLB definition — a Dockerfile parse or frontend-fetch failure.
• toomanyrequests: You have reached your pull rate limit — the unwrapped Docker Hub rate-limit message.
• error checking context: no such file or directory — a build-context problem before solving begins.
• no space left on device — the disk-pressure cause of many Unknown solves.

Frequently Asked Questions

What does rpc error: code = Unknown actually mean? It is BuildKit’s gRPC wrapper around the real failure. The message after desc = is the genuine error; always read and act on that, not the Unknown code.

Why do I get a 429 during builds but not when pulling manually? Anonymous pulls share a low Docker Hub rate limit. A build may fetch several base-image tokens quickly, tripping the limit. Running docker login raises your quota.

How do I see the failing build step clearly? Add --progress=plain to docker build. The default compact progress collapses output and hides the step that produced the desc message.

Could a full disk cause this even with a valid Dockerfile? Yes. When the builder cannot write layers it fails the solve with an Unknown code. Check docker system df and run docker builder prune. For more, see the Docker guides.