How to fix failed to solve: failed to load cache key: cache key not found in Docker

DockerINTERMEDIATEMEDIUM

This error occurs when Docker BuildKit cannot import cache from a specified source during builds. The cache location may not exist yet, be inaccessible, or contain incompatible data. Common fixes include ensuring the cache exists, using correct cache backend configuration, or handling first-run scenarios gracefully.

What this error means

The "failed to load cache key: cache key not found" error in Docker indicates that BuildKit's cache import mechanism cannot find the requested cache data at the specified location. This typically occurs when using the `--cache-from` flag with Docker Buildx or in CI/CD pipelines where build cache is stored externally. Docker BuildKit supports several cache backends: local filesystem, registry-based cache, and GitHub Actions cache (gha). When you specify `--cache-from`, BuildKit attempts to load previously cached layers from that source. If the cache doesn't exist (common on first builds), is corrupted, or the cache format is incompatible, this error is thrown. This error is particularly common in CI/CD environments where cache persistence across builds is configured but may not exist on the first run or after cache expiration. It can also occur when cache backend settings are misconfigured, when using the wrong Docker driver, or when there's a mismatch between cache export and import configurations.

How to fix "failed to solve: failed to load cache key: cache key not found"

1Accept missing cache on first build

The cache-from warning is expected on the first build when no cache exists yet. BuildKit will proceed without cache and build from scratch.

bash

# The warning is informational - the build will continue
# WARNING: local cache import at /tmp/.buildx-cache not found

# After the first successful build with --cache-to, subsequent builds
# will find and use the cache
docker buildx build \
  --cache-from type=local,src=/tmp/.buildx-cache \
  --cache-to type=local,dest=/tmp/.buildx-cache,mode=max \
  -t myimage .

If the warning becomes an error, proceed to the next troubleshooting steps.

2Verify cache backend configuration

Ensure your cache-from and cache-to configurations match and use supported backends:

bash

# Local cache backend
docker buildx build \
  --cache-from type=local,src=/path/to/cache \
  --cache-to type=local,dest=/path/to/cache,mode=max \
  -t myimage .

# Registry cache backend
docker buildx build \
  --cache-from type=registry,ref=myregistry/cache:latest \
  --cache-to type=registry,ref=myregistry/cache:latest,mode=max \
  --push -t myregistry/myimage:latest .

# GitHub Actions cache (gha)
docker buildx build \
  --cache-from type=gha \
  --cache-to type=gha,mode=max \
  -t myimage .

Important: Use mode=max to cache all layers (including intermediate stages), not just the final image layers.

3Check Docker driver compatibility

Not all cache backends work with the default Docker driver. Some require docker-container or other drivers:

bash

# Check current builder and driver
docker buildx ls

# Create a new builder with docker-container driver
docker buildx create --name mybuilder --driver docker-container --use

# For the default docker driver, enable containerd image store
# Edit Docker daemon config or use Docker Desktop settings

Driver requirements:
- docker driver: Supports inline, local, registry, and gha cache (with containerd image store)
- docker-container driver: Supports all cache backends
- kubernetes driver: Supports all cache backends

If you see "cache export is not supported for the docker driver", switch to docker-container driver or enable containerd.

4Fix GitHub Actions cache configuration

For GitHub Actions workflows, ensure you're using the correct setup:

yaml

name: Build
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        # Ensures latest buildx version with GHA cache support

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: user/app:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

For multiple images, use unique cache scopes:

yaml

- name: Build frontend
        uses: docker/build-push-action@v6
        with:
          context: ./frontend
          cache-from: type=gha,scope=frontend
          cache-to: type=gha,mode=max,scope=frontend

      - name: Build backend
        uses: docker/build-push-action@v6
        with:
          context: ./backend
          cache-from: type=gha,scope=backend
          cache-to: type=gha,mode=max,scope=backend

5Update Buildx for legacy API deprecation

If you see errors about legacy GitHub Cache service API (deprecated April 2025), update Docker Buildx:

bash

# Check current buildx version
docker buildx version

# Update to latest buildx (requires v0.21.0+ for new GHA cache API)
# On self-hosted runners:
docker buildx create --name builder --driver docker-container --bootstrap --use

For GitHub Actions, use the setup action which handles versioning:

yaml

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  # This automatically installs a compatible version

If pinning a version, ensure it's 0.21.0 or newer for GitHub Actions cache support.

6Initialize local cache directory

For local cache backends, ensure the directory structure exists:

bash

# Create cache directory if it doesn't exist
mkdir -p /tmp/.buildx-cache

# For CI/CD with local cache, conditionally add cache-from
if [ -f "/tmp/.buildx-cache/index.json" ]; then
  CACHE_FROM="--cache-from type=local,src=/tmp/.buildx-cache"
else
  CACHE_FROM=""
fi

docker buildx build \
  $CACHE_FROM \
  --cache-to type=local,dest=/tmp/.buildx-cache-new,mode=max \
  -t myimage .

# Move new cache to cache location (atomic update)
rm -rf /tmp/.buildx-cache
mv /tmp/.buildx-cache-new /tmp/.buildx-cache

Note: Writing cache to a new directory and then moving it prevents corruption from interrupted builds.

7Handle registry cache authentication

For registry-based cache, ensure you're authenticated:

bash

# Login to your registry
docker login myregistry.com

# Use registry cache with authentication
docker buildx build \
  --cache-from type=registry,ref=myregistry.com/cache:buildcache \
  --cache-to type=registry,ref=myregistry.com/cache:buildcache,mode=max \
  --push -t myregistry.com/myimage:latest .

For GitHub Container Registry:

yaml

- name: Login to GHCR
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

- name: Build with registry cache
  uses: docker/build-push-action@v6
  with:
    cache-from: type=registry,ref=ghcr.io/${{ github.repository }}/cache:buildcache
    cache-to: type=registry,ref=ghcr.io/${{ github.repository }}/cache:buildcache,mode=max

8Clear and rebuild cache

If cache is corrupted, clear it and rebuild:

bash

# Clear buildx cache
docker buildx prune -a

# Remove local cache directory
rm -rf /tmp/.buildx-cache

# Build fresh with new cache
docker buildx build \
  --no-cache \
  --cache-to type=local,dest=/tmp/.buildx-cache,mode=max \
  -t myimage .

# Subsequent builds can now use the cache
docker buildx build \
  --cache-from type=local,src=/tmp/.buildx-cache \
  --cache-to type=local,dest=/tmp/.buildx-cache,mode=max \
  -t myimage .

For registry cache, push a fresh cache image:

bash

docker buildx build \
  --no-cache \
  --cache-to type=registry,ref=myregistry/cache:latest,mode=max \
  --push -t myregistry/myimage:latest .

Advanced notes

Understanding BuildKit cache backends:

BuildKit supports multiple cache export/import backends:

1. inline: Embeds cache metadata in the image itself. Simple but increases image size.

bash

docker buildx build --cache-to type=inline --push -t myimage .
   docker buildx build --cache-from myimage -t myimage .

2. local: Stores cache on local filesystem. Fast but not shared across machines.

bash

--cache-to type=local,dest=/path,mode=max
   --cache-from type=local,src=/path

3. registry: Stores cache as a separate image in a registry. Shareable across machines.

bash

--cache-to type=registry,ref=myregistry/cache:latest,mode=max
   --cache-from type=registry,ref=myregistry/cache:latest

4. gha: GitHub Actions cache. Integrated with GitHub's caching infrastructure.

bash

--cache-to type=gha,mode=max
   --cache-from type=gha

5. s3: Amazon S3 or compatible storage. Enterprise-scale caching.

bash

--cache-to type=s3,region=us-east-1,bucket=mybucket,name=myapp
   --cache-from type=s3,region=us-east-1,bucket=mybucket,name=myapp

Cache modes:
- mode=min (default): Only cache layers in the final image
- mode=max: Cache all layers including intermediate build stages

Debugging cache issues:

bash

# Verbose build output
docker buildx build --progress=plain ...

# Check what's in local cache
ls -la /tmp/.buildx-cache/
cat /tmp/.buildx-cache/index.json | jq .

# Inspect registry cache manifest
docker manifest inspect myregistry/cache:latest

Multi-platform cache considerations:
When building multi-platform images, each platform's layers are cached separately. Ensure your cache storage has sufficient space:

bash

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --cache-to type=registry,ref=myregistry/cache:multiarch,mode=max \
  --push -t myimage .

Cache key calculation:
BuildKit calculates cache keys based on:
- Dockerfile instructions
- Build arguments
- Source file contents (for COPY/ADD)
- Base image digest

If any of these change, the cache key changes and cache misses occur. Use .dockerignore to exclude files that shouldn't affect cache keys.

How to fix failed to solve: failed to load cache key: cache key not found in Docker

What this error means

Typical symptoms

Common causes

How to fix "failed to solve: failed to load cache key: cache key not found"

Advanced notes

Related errors

Official resources & further reading