Docker BuildKit "failed to solve: lazy initialization" - Fix Stale Cache Refs

BuildKit defers (lazily) pulling some layers until it needs them. "lazy initialization" fails when one of those deferred blobs - from a base image or an imported cache - can no longer be fetched.

What this error means

A build fails with failed to solve: ... during lazy initialization or lazy blob ... not found, often partway through after earlier steps succeeded. It is frequently transient (registry blip) but can persist if a cache reference is genuinely gone.

docker build output

ERROR: failed to solve: failed to do request: Head "https://registry/v2/.../blobs/sha256:..."
during lazy initialization: ... (or: lazy blob sha256:... not found)

Common causes

A deferred base-image or cache blob became unreachable

BuildKit recorded a lazy reference to a layer and tried to fetch it later, but the registry returned an error or the blob was garbage-collected in the meantime.

Transient registry/network failure mid-build

The deferred fetch hit a registry 5xx or a network blip. This class is flaky and often clears on retry.

Stale imported cache (--cache-from) no longer present

A --cache-from registry cache that has been pruned leaves lazy references that cannot be resolved when BuildKit finally needs them.

How to fix it

Retry, then rebuild without the stale cache

A transient lazy-fetch failure usually passes on retry; a persistent one means the cache reference is gone.

Terminal

docker buildx build . || docker buildx build --no-cache .
# or drop a pruned --cache-from and re-export fresh cache

Pin base images by digest and refresh cache

Reference base images by an immutable digest so lazy refs stay valid.
Re-export the build cache (--cache-to) so imported caches are current.
Mirror critical base images so a Hub blip does not break the lazy fetch.

How to prevent it

Pin base images by digest to keep lazy references stable.
Keep --cache-from references fresh and not subject to aggressive pruning.
Mirror base images to reduce dependence on a single registry during the build.