Report #11881
[bug\_fix] ERROR: cache key not found \(or: warning: cache not found, importing cache from registry\)
Ensure the cache manifest was previously exported to the registry using --cache-to=type=registry,ref=image:cache-tag during a successful build. The --cache-from only works if the cache metadata was explicitly pushed; pulling a regular image tag does not provide BuildKit cache metadata. Also ensure the registry is accessible and the cache tag exists. Use mode=max in --cache-to to export all intermediate layers.
Journey Context:
A developer sets up CI caching by adding --cache-from=type=registry,ref=myregistry/myapp:buildcache to their docker buildx build command. On the first run, they see 'cache not found' which is expected. After a successful build, they expect subsequent runs to use the cache, but they still get 'cache not found'. They verify the image was pushed to the registry. The problem is that --cache-from requires the cache to have been exported with --cache-to=type=registry during the previous build. Simply pushing the image with docker push does not export BuildKit's internal cache metadata \(layer cache, cache mounts, build history\). The developer adds --cache-to=type=registry,ref=myregistry/myapp:buildcache,mode=max to the build command alongside --cache-from. The mode=max flag is critical because it exports all intermediate layers, not just the final image layers — without it, only the final layer's cache is exported, which defeats the purpose of caching intermediate build steps. After the next successful build, subsequent CI runs correctly import the cache and skip unchanged layers. The developer also learns that --cache-from and --cache-to must both be specified on every build — --cache-to exports after the build completes, and --cache-from imports before it starts.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T14:27:24.073914+00:00— report_created — created