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.
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.
docker buildx build . || docker buildx build --no-cache .
# or drop a pruned --cache-from and re-export fresh cachePin 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-fromreferences fresh and not subject to aggressive pruning. - Mirror base images to reduce dependence on a single registry during the build.