🐳 Docker Error Guide: 'failed to export image' buildx Export and Push Failure

Exact Error Message

ERROR: failed to solve: failed to export image: unexpected status from PUT request
to https://registry.example.com/v2/app/blobs/uploads/...: 401 Unauthorized

You may also see related forms such as failed to solve: failed to export image: exit status 1, error writing layer blob, failed to push ...: denied: requested access to the resource is denied, or failed to solve: failed to compute cache key during a cache export. All are export-stage failures from BuildKit / docker buildx.

What It Means

docker buildx builds with BuildKit, which splits a build into a solve phase (running Dockerfile steps) and an export phase (writing the result somewhere). The message failed to export image means the build itself completed but BuildKit could not write the finished image to the destination you asked for: a registry (--push), the local Docker image store, a tarball, or an OCI directory (--output).

Because the export target varies, the root cause varies too. The most common is registry authentication or permission failure when pushing, followed by cache-export configuration problems and mismatches between multi-platform builds and the chosen output type.

Common Causes

• Not logged in to the target registry, or the credential has expired, so --push returns 401 or denied.
• The repository does not exist or the token lacks write/push scope.
• A multi-platform build (--platform linux/amd64,linux/arm64) is exported with --load, which only supports a single platform.
• The default docker driver is in use, which cannot export multi-platform images or push directly; a docker-container builder is required.
• A cache export (--cache-to type=registry,...) points at a location the credential cannot write.
• Disk pressure or a full /var/lib/docker interrupts the layer blob write.

Diagnostic Commands

Confirm which builder and driver are active:

docker buildx ls

Check that you are authenticated to the registry:

docker login registry.example.com
cat ~/.docker/config.json

Re-run the build with full progress output to see the failing export step:

docker buildx build --progress=plain --push -t registry.example.com/app:ci .

Verify free disk space if blob writes fail midway:

docker system df
df -h /var/lib/docker

Step-by-Step Resolution

1. Read the tail of the error. A 401/denied means auth; no space left on device means disk; --load with multiple platforms means an output-type mismatch.

2. For auth failures, log in with a credential that has push access, then retry:

docker login registry.example.com -u ci-bot
docker buildx build --push -t registry.example.com/app:ci .

3. For multi-platform builds, create and use a docker-container builder, which supports multi-arch export and cache export:

docker buildx create --name multi --driver docker-container --use
docker buildx inspect --bootstrap

4. Choose an export type that matches your intent. Use --push for a registry, --load for a single-platform local image, or --output for a tarball:

# push a multi-arch image
docker buildx build --platform linux/amd64,linux/arm64 --push -t registry.example.com/app:ci .

# load a single-platform image locally
docker buildx build --platform linux/amd64 --load -t app:dev .

# export to an OCI tarball
docker buildx build --output type=oci,dest=app.tar .

5. If a cache export is failing, confirm the cache destination is writable, or fall back to inline cache:

docker buildx build --push -t registry.example.com/app:ci \
  --cache-to type=inline --cache-from registry.example.com/app:ci .

6. If the write aborted on disk space, prune and retry:

docker buildx prune -f
docker system prune -f

7. Re-run and confirm the export finishes:

=> exporting to image
=> => pushing layers
=> => pushing manifest for registry.example.com/app:ci

Prevention

• Run docker login (or configure a credential helper) as an explicit early step in CI so exports never hit stale tokens.
• Use a dedicated docker-container builder for any multi-platform or cache-export workflow; do not rely on the default docker driver.
• Match the output flag to the job: --push to publish, --load for local single-arch, --output for artifacts.
• Monitor docker system df in long-lived CI runners and prune on a schedule to avoid mid-push disk exhaustion.
• Grant CI credentials the minimum push scope up front so denied errors surface at login, not at export.

Related Errors

• failed to solve: failed to compute cache key — a missing build context file or bad --cache-from, earlier than export.
• denied: requested access to the resource is denied — the push-specific permission form of this error.
• docker exporter feature is currently not supported for docker driver — you need a docker-container builder.
• no space left on device — a disk problem that surfaces during the export write.

Frequently Asked Questions

Why does the build succeed but exporting fails? BuildKit separates solving from exporting. The steps ran fine, but writing the result to the registry, image store, or file failed, most often due to registry auth.

Can I use —load with a multi-platform build? No. --load writes to the local Docker image store, which holds one platform. Use --push for multi-arch, or build a single --platform for --load.

How do I fix a 401 on export? Run docker login against the target registry with a token that has push scope, confirm the entry in ~/.docker/config.json, then rebuild with --push.

Do I need a special builder for cache export? Yes for registry cache. Create a docker-container builder with docker buildx create --driver docker-container, or fall back to --cache-to type=inline. Generate export-flag and cache fixes fast with the DevOps AI prompt library.

What if the export dies with no space left on device? Free space with docker buildx prune and docker system prune, or point /var/lib/docker at a larger volume, then rebuild. More fixes are in the Docker guides.