Docker "failed to solve" BuildKit Errors - Diagnose and Fix

failed to solve is BuildKit’s catch-all wrapper. The real cause is always in the line just after it - the trick is reading the right part of the message.

What this error means

A docker build (with BuildKit, the default in modern Docker) aborts with ERROR: failed to solve: followed by a more specific reason. The wrapper text is generic; the suffix is the actual problem.

docker build output

ERROR: failed to solve: failed to compute cache key: failed to calculate
checksum of ref ...: "/app/package.json": not found

Common causes

"not found" - a COPY source is missing

BuildKit cannot find a file referenced by COPY/ADD. Usually the path is wrong relative to the build context, or the file is excluded by .dockerignore.

"failed to fetch" / network errors

A RUN step that downloads packages hit a transient network or registry failure. This class is flaky and often passes on retry.

"no match for platform" - architecture mismatch

The requested --platform has no matching image, common when building arm64 on an amd64 runner without emulation set up.

How to fix it

Read the suffix and act on it

Look at the text immediately after failed to solve: - that is the real error.
For "not found", check the path is relative to the build context and not excluded by .dockerignore.
For network errors, retry the build; if it persists, pin or mirror the dependency.
For platform errors, set up QEMU with docker/setup-qemu-action or build natively for the target arch.

Get more detail

Re-run with plain progress output so the full failing command and its logs are visible.

Terminal

docker build --progress=plain --no-cache .

How to prevent it

Keep .dockerignore accurate so context paths stay predictable.
Pin base images and downloaded dependencies by version or digest.
Set up multi-arch tooling explicitly when building for non-native platforms.