buildx could not load a cache key from the configured cache backend. The --cache-from reference is missing, unreadable, or the cache backend (registry or GitHub Actions cache) had a transient error while importing.
What this error means
A build logs failed to load cache key for a --cache-from source. The build may continue without that cache (slower) or fail if the cache import is treated as fatal.
docker
#3 importing cache manifest from ghcr.io/myorg/api:buildcache
#3 ERROR: failed to load cache key: ghcr.io/myorg/api:buildcache: not found
# or a transient: failed to load cache key: ... 503 Service Unavailable
Common causes
The cache reference does not exist yet
On the first build (or after the cache tag was deleted), --cache-from points at a ref that is not there, so there is no key to load.
No read access to the cache backend
A registry cache ref the job cannot pull, or a GHA cache scope it cannot read, fails the cache import with an auth/not-found error.
Transient registry error during import
A 5xx from the registry while reading the cache manifest fails the load and usually clears on retry.
How to fix it
Tolerate a missing cache and authenticate for reads
Treat a missing cache as a cold build; log in so the cache ref is readable.
A registry blip during cache import clears on retry; a persistent not-found just means cold build.
How to prevent it
Authenticate to the cache backend before importing cache.
Treat a missing cache ref as a normal cold build, not a failure.
Use mode=max cache export so later builds have keys to load.
Frequently asked questions
What causes ""failed to load cache key""?
On the first build (or after the cache tag was deleted), --cache-from points at a ref that is not there, so there is no key to load.
How do I fix "failed to load cache key"?
Treat a missing cache as a cold build; log in so the cache ref is readable.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
