GitHub Actions buildx "failed to export gha cache"
Buildx can export layer caches to the GitHub Actions cache via cache-to type=gha. Missing scope inputs or a transient cache-service hiccup can fail the export. Config issues are deterministic; a one-off cache-service 5xx is transient.
What this error means
The build succeeds building layers but fails exporting them to the gha cache backend at the end of the step.
github-actions
ERROR: failed to solve: error writing layer blob: failed to export cache:
unexpected status code from cache service: 503Common causes
Missing or wrong cache-to configuration
cache-to type=gha is malformed or the build lacks the inputs buildx needs to address the cache.
Transient cache-service error
An intermittent 5xx from the Actions cache service interrupts the export.
How to fix it
Configure gha cache export correctly
- Set cache-from and cache-to with type=gha and mode=max for full layer caching.
- Ensure the buildx builder uses the docker-container driver.
- Re-run on a transient cache-service error.
.github/workflows/build.yml
- uses: docker/build-push-action@v6
with:
context: .
cache-from: type=gha
cache-to: type=gha,mode=maxHow to prevent it
- Use the docker-container driver and a well-formed type=gha cache config.
- On Latchkey managed runners, transient cache-service errors during layer export are retried automatically so a one-off export blip does not fail the build.
Frequently asked questions
What causes ""failed to export" gha cache"?
cache-to type=gha is malformed or the build lacks the inputs buildx needs to address the cache.
How do I fix "failed to export" gha cache?
Configure gha cache export correctly
Related guides
GitHub Actions setup-buildx "driver-opts invalid"Fix the GitHub Actions docker/setup-buildx-action error caused by invalid driver-opts input.
GitHub Actions cache "size exceeds 10GB limit"Fix the GitHub Actions cache error where a single cache entry exceeds the 10GB per-cache size limit.
GitHub Actions cache "another job is already creating this cache"Fix the GitHub Actions cache warning where another job is already creating the same cache key concurrently.