How to fix error exporting cache: failed to export cache in Docker

What this error means

The "error exporting cache: failed to export cache" message in Docker indicates that BuildKit's cache export mechanism has failed during an image build operation. This error typically appears when using the `--cache-to` flag with `docker buildx build` to export build cache layers to an external location like a container registry or local directory. BuildKit, Docker's modern build subsystem, supports exporting cache metadata and layers separately from the final image. This enables faster rebuilds by reusing previously computed layers. However, this advanced caching feature requires specific driver configurations that aren't available with Docker's default setup. The error can manifest in several forms: "cache export feature is currently not supported for docker driver", "failed to export cache: invalid incomplete links", or "error writing layer blob" messages. Each variant points to a different underlying cause, but they all relate to BuildKit's inability to complete the cache export phase of the build process.

Typical symptoms

• docker buildx build fails with 'error exporting cache: failed to export cache'
• CI/CD pipelines fail at the cache export step after successful image build
• 'cache export feature is currently not supported for docker driver' error
• GitHub Actions build-push-action fails with cache-related errors
• 'error writing layer blob: content sha256:...: not found' during cache export
• Build succeeds locally but fails when --cache-to is added
• 'failed to solve: rpc error: invalid incomplete links' error
• Cache export step hangs indefinitely in multi-stage builds

Common causes

1. Using the default docker driver which doesn't support cache export features
2. Missing docker buildx setup in CI/CD pipelines (GitHub Actions, GitLab CI)
3. Registry authentication issues preventing cache layer push
4. Corrupted cache chain from parallel builds or interrupted operations
5. BuildKit version incompatibility with cache export type (inline, registry, local, gha)
6. Insufficient permissions to write to the cache destination (registry or filesystem)
7. Race conditions when multiple builds export cache simultaneously
8. S3 or other external cache backends not properly configured or supported

How to fix "error exporting cache: failed to export cache"

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

# Verify the builder is active
docker buildx ls

# Now run your build with cache export
docker buildx build --cache-to type=registry,ref=myregistry/myimage:cache \
  --cache-from type=registry,ref=myregistry/myimage:cache \
  -t myimage:latest .

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

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

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

{
  "features": {
    "containerd-snapshotter": true
  }
}

# Login to your registry
docker login myregistry.com

# For AWS ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account>.dkr.ecr.us-east-1.amazonaws.com

# For Google Artifact Registry
gcloud auth configure-docker us-docker.pkg.dev

# Test push access with a small image
docker pull alpine
docker tag alpine myregistry.com/test:cache-test
docker push myregistry.com/test:cache-test

# Build with inline cache (works with default driver)
docker build --build-arg BUILDKIT_INLINE_CACHE=1 -t myimage:latest .

# Push the image (cache metadata included)
docker push myimage:latest

# Later builds can use this image as cache source
docker build --cache-from myimage:latest -t myimage:latest .

# Check BuildKit version
docker buildx version

# Recreate the builder pinned to the latest BuildKit
docker buildx create --name newbuilder --driver docker-container \
  --driver-opt image=moby/buildkit:latest --use

# Clear the local BuildKit cache for the active builder
docker buildx prune -f

# For registry/local cache, push to a NEW cache ref to abandon the corrupted chain
docker buildx build \
  --cache-to type=registry,ref=myregistry/myimage:cache-v2,mode=max \
  --cache-from type=registry,ref=myregistry/myimage:cache-v2 \
  -t myimage:latest .

# Use mode=min instead of mode=max to export less cache data
docker buildx build --cache-to type=registry,ref=myimage:cache,mode=min .

# Export cache for specific stages only
docker buildx build --target builder --cache-to type=local,dest=./cache .

# Set a timeout for the build
timeout 30m docker buildx build --cache-to type=registry,ref=myimage:cache .

# Build without cache export to confirm the build itself works
docker buildx build -t myimage:latest .

# Then test cache export separately
docker buildx build --cache-to type=local,dest=./test-cache .

# Export cache to local directory
docker buildx build \
  --cache-to type=local,dest=./buildcache \
  --cache-from type=local,src=./buildcache \
  -t myimage:latest .

# GitHub Actions with local cache
- name: Build with local cache
  uses: docker/build-push-action@v5
  with:
    context: .
    cache-from: type=local,src=/tmp/.buildx-cache
    cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max

# Move cache to prevent unbounded growth
- name: Move cache
  run: |
    rm -rf /tmp/.buildx-cache
    mv /tmp/.buildx-cache-new /tmp/.buildx-cache

Advanced notes

# Enable BuildKit debug output
BUILDKIT_PROGRESS=plain docker buildx build --cache-to type=registry,ref=img:cache .

# Check builder logs
docker logs buildx_buildkit_mybuilder0

# Inspect cache manifest in registry
docker manifest inspect myregistry/myimage:cache

docker buildx build --platform linux/amd64,linux/arm64 \
  --cache-to type=registry,ref=myimage:cache \
  --cache-from type=registry,ref=myimage:cache .

Frequently asked questions

What does "error exporting cache: failed to export cache" mean?

The "error exporting cache: failed to export cache" message in Docker indicates that BuildKit's cache export mechanism has failed during an image build operation. This error typically appears when using the --cache-to flag with docker buildx build to export build cache layers to an external location like a container registry or local directory. BuildKit, Docker's modern build subsystem, supports exporting cache metadata and layers separately from the final image.

How do I fix "error exporting cache: failed to export cache"?

This BuildKit error occurs when Docker cannot export build cache to a registry or local storage. The most common cause is using the default docker driver, which doesn't support cache export. Fix it by switching to the docker-container driver or enabling the containerd image store.

What causes "error exporting cache: failed to export cache"?

Using the default docker driver which doesn't support cache export features Missing docker buildx setup in CI/CD pipelines (GitHub Actions, GitLab CI) Registry authentication issues preventing cache layer push

Is the "error exporting cache: failed to export cache" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• failed to solve: failed to load cache key: cache key not found

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

  MEDIUM

• ERROR: failed to solve: failed to push: unsupported platform

  How to fix 'failed to push: unsupported platform' in Docker Buildx

  MEDIUM

• runtime create failed: container_linux.go:380: starting container process caused: process_linux.go:545: container init caused: fork/exec: cannot allocate memory

  How to fix "cannot allocate memory" in Docker

  HIGH

• ERROR: multiple platforms feature is currently not supported for docker driver

  How to fix 'multiple platforms feature is currently not supported for docker driver' in Docker

  MEDIUM

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 📖
  Docker Docs: Build cache backends(Official Docs)
• 📖
  Docker Docs: Build drivers(Official Docs)
• 🐙
  BuildKit: Failed to export cache - invalid incomplete links(GitHub)
• 🐙
  Buildx: Exporting cache crashes with content not found(GitHub)
• 🐙
  BuildKit: Cache with BUILDKIT_INLINE_CACHE fails every second time(GitHub)
• 💬
  Stack Overflow: buildx cache export not supported for docker driver(Stack Overflow)
• 📝
  Dev.to: 100 Common Docker Errors & Solutions