docker build failed (tested)

docker build failing is almost always one of three things: a COPY/ADD instruction pointing at a file that isn't in the build context, a RUN command that exits non-zero, or a FROM base image BuildKit can't fetch. We reproduced all three on a live box running Docker 29.8.1 with BuildKit, and recorded the exact error text each one prints, so you can match yours below. This is about docker build itself (building an image from a Dockerfile); if your failure happens on docker compose up instead, see Docker Compose Up Errors, which covers a different set of errors (bad service names, port conflicts, bad compose-file image tags).

1. Quick lookup: match your error text

2. "failed to calculate checksum of ref" / "failed to compute cache key"

This is the single most common docker build failure. It means a COPY or ADD instruction names a file or directory that does not exist in the build context (the directory you pass to docker build, not your whole filesystem). We wrote this Dockerfile in an otherwise-empty directory:

FROM alpine:latest
COPY nonexistent-file.txt /app/

Running docker build -t forever-guidetest:copy . against that directory gave:

#5 [2/2] COPY nonexistent-file.txt /app/
#5 ERROR: failed to calculate checksum of ref vdvaeexjgxbl2jy563csl2hvu::kddjrvrdpu2p8m21s3wrvvy2l: "/nonexistent-file.txt": not found
------
 > [2/2] COPY nonexistent-file.txt /app/:
------
Dockerfile:2
--------------------
   1 |     FROM alpine:latest
   2 | >>> COPY nonexistent-file.txt /app/
   3 |
--------------------
ERROR: failed to build: failed to solve: failed to compute cache key: failed to calculate checksum of ref vdvaeexjgxbl2jy563csl2hvu::kddjrvrdpu2p8m21s3wrvvy2l: "/nonexistent-file.txt": not found

Reading this: the bottom line, failed to solve: failed to compute cache key: failed to calculate checksum of ref ...: "/path": not found, is BuildKit's generic solve error wrapping the specific cache-key error, which itself wraps the real problem: the named path doesn't exist relative to the build context root. The ref vdvaeexjgxbl2jy563csl2hvu::... part is an internal BuildKit cache reference ID — ignore it, it's not useful for debugging, only the quoted path and "not found" matter.

Fix: check three things, in order: (1) the path is spelled correctly and relative to the build context (the last argument to docker build, often .), (2) the file isn't excluded by a .dockerignore file in that context, (3) if you're copying from a subdirectory, that you didn't forget to pass that subdirectory as the context (docker build -f sub/Dockerfile sub/, not just sub/Dockerfile .).

3. "failed to solve: process ... did not complete successfully: exit code: N"

This is a different failure: the Dockerfile and build context are fine, but a RUN command inside the build itself returned a non-zero exit code. We tested this directly:

FROM alpine:latest
RUN exit 1

$ docker build -t forever-guidetest:run1 .
...
#5 [2/2] RUN exit 1
#5 ERROR: process "/bin/sh -c exit 1" did not complete successfully: exit code: 1
------
ERROR: failed to build: failed to solve: process "/bin/sh -c exit 1" did not complete successfully: exit code: 1

Note what's different from Section 2: there's no "failed to compute cache key" in the middle. A failing RUN goes straight from failed to solve to process "..." did not complete successfully, because BuildKit got far enough to actually execute the step — it just failed while running, instead of failing to even start.

Fix: the command printed in quotes (/bin/sh -c exit 1 here) is the literal shell command BuildKit ran. Run that same command manually (in a container from the same base image, or locally) to see its real output above the Dockerfile's cached build log — BuildKit only shows the exit code by default, not the command's stdout/stderr, unless you add --progress=plain or the step wasn't cached.

4. Exit codes: the build surfaces your RUN command's own exit code

The number after exit code: is not a Docker error code — it's whatever your RUN command itself returned. We confirmed this by changing only the exit code:

FROM alpine:latest
RUN exit 42

#5 [2/2] RUN exit 42
#5 ERROR: process "/bin/sh -c exit 42" did not complete successfully: exit code: 42
------
ERROR: failed to build: failed to solve: process "/bin/sh -c exit 42" did not complete successfully: exit code: 42

Exit 1 produced "exit code: 1", exit 42 produced "exit code: 42" — nothing else in the message changed. This matters when a RUN calls a script or tool with meaningful exit codes (test runners, linters, package managers): the number in BuildKit's error is your direct clue to what actually failed inside that step, before you go looking at logs.

5. "failed to resolve source metadata" and registry/auth errors on FROM

These errors happen before BuildKit even starts your build — it's failing to fetch the FROM base image. We tested the fast, free case: a FROM referencing an image repository that doesn't exist at all (not just a bad tag):

FROM nonexistent-image-xyz123:doesnotexist
RUN echo hi

#2 [internal] load metadata for docker.io/library/nonexistent-image-xyz123:doesnotexist
#2 ERROR: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed
------
ERROR: failed to build: failed to solve: nonexistent-image-xyz123:doesnotexist: failed to resolve source metadata for docker.io/library/nonexistent-image-xyz123:doesnotexist: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed

This is a distinct case from a bad tag on an image that does exist (covered in Docker Compose Up Errors, section 4, where alpine:bad-tag gives failed to resolve reference ... not found). When the repository name itself doesn't exist, the Hub's anonymous-pull auth layer rejects the token request first, so you get "pull access denied ... insufficient_scope" wrapped in "failed to resolve source metadata", not a plain "not found".

Three related messages we did not reproduce, because each needs a private registry with broken auth or an untrusted TLS setup, which this box doesn't have — per Docker/BuildKit's own docs and issue tracker, not measured here:

• failed to fetch anonymous token / failed to fetch oauth token: BuildKit reached the registry's /v2/ endpoint but the token request to its auth server failed — typically the auth server is down, blocked by a firewall/proxy, or credentials in ~/.docker/config.json are stale for a private registry.
• failed to verify certificate: x509: certificate signed by unknown authority: the registry presents a self-signed or internally-issued TLS certificate that isn't in the daemon's trust store. Per Docker's docs, the fix is to add the registry's CA certificate under /etc/docker/certs.d/<registry-host>/ca.crt, not to disable TLS verification.
• x509: certificate has expired or certificate is not valid for any names: same family, but the cert itself is expired or missing a Subject Alternative Name for the host you're connecting to — a registry operator problem, not a client misconfiguration.

6. Checklist: narrowing down a build failure fast

• Read the last line of the error first (ERROR: failed to build: failed to solve: ...) — it names the exact failing step and instruction type.
• failed to calculate checksum / failed to compute cache key → a COPY/ADD path problem (Section 2). Check the build context and .dockerignore.
• process "..." did not complete successfully: exit code: N → a RUN command failed while executing (Section 3). Re-run that exact command yourself to see its real output.
• failed to resolve source metadata, pull access denied, oauth token, or x509 → BuildKit can't fetch the FROM image (Section 5). Check the repository/tag spelling, registry login, and (for private registries) TLS certs.
• Add --progress=plain to docker build to see full, unbuffered step output instead of the collapsed TTY view — most useful when a RUN step's own stdout/stderr is what you actually need.
• If the failure is on docker compose up rather than a plain docker build, see Docker Compose Up Errors instead — compose has its own error set (bad service names, port conflicts, credential helpers).

Written with AI assistance. Measured on 2026-10-02 with Docker 29.8.1 (BuildKit, containerd image store) on Linux, building from Dockerfiles under /tmp with image tags prefixed forever-guidetest. The real x509 certificate / OAuth token failure cases are from Docker's and BuildKit's own docs and GitHub issues, not measured, because reproducing them needs a private registry with broken auth. PlainHeaders is our extension; Docker and BuildKit are free.