Docker buildx "failed to push" to Registry in CI

buildx built the image but could not push it. failed to solve: failed to push <ref> means the registry rejected or could not receive the push - usually missing/expired auth, a repository that does not exist, or a transient registry error.

What this error means

A docker buildx build --push (or build-push-action with push: true) fails at the push with failed to solve: failed to push <ref>: ..., naming an auth, not-found, or server error.

ERROR: failed to solve: failed to push ghcr.io/myorg/api:1.4.2:
unexpected status from POST request to https://ghcr.io/v2/myorg/api/blobs/uploads/: 401 Unauthorized

Common causes

Not logged in (or token expired) for the registry

A push needs valid write credentials for the target registry. A missing docker login, a wrong token, or an expired one fails the push with 401/403.

The target repository does not exist or is not writable

Some registries (ECR) require the repository to exist first; a namespace your token cannot write fails the push.

Transient registry error during upload

A 5xx or dropped connection while uploading blobs fails the push and usually clears on retry.

How to fix it

Authenticate with write scope before pushing

Log in to the exact registry with a token that can write the repository.

echo "${{ secrets.GHCR_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
docker buildx build --push -t ghcr.io/myorg/api:1.4.2 .

Ensure the repo exists and retry transients

Create the repository if the registry requires it; retry a transient 5xx.

How to prevent it

• Log in to the target registry with write scope in the same job.
• Create ECR/registry repositories before the first push.
• Wrap pushes in a bounded retry for transient registry 5xx.

Related guides