Docker "failed commit on ref ... unexpected status" - Fix Push/Commit Errors

BuildKit tried to commit (finalize) a layer or manifest to the registry during an export/push and the registry returned an unexpected status. The build itself ran; the upload step failed.

What this error means

A docker buildx build --push fails near the end with failed commit on ref "layer-sha256:...": unexpected status: 401/403/413/500. The image built fine locally; the export to the registry is what broke.

docker buildx output

ERROR: failed to solve: failed commit on ref "manifest-sha256:9f2c...":
unexpected status: 500 Internal Server Error

Common causes

Registry-side error during the commit (5xx)

A transient 500/503 from the registry while finalizing a blob or manifest. This is server-side and usually clears on retry.

Auth/permission failure on export (401/403)

The push credentials expired or lack write scope, so the commit of the layer is rejected - even though the local build succeeded.

Layer too large for the registry (413)

A single oversized layer can exceed a registry’s upload limit, returning 413 on commit.

How to fix it

Retry transient commits; re-auth for 401/403

Distinguish a transient 5xx from an auth failure by the status code.

Terminal

docker login ghcr.io -u "$USER" -p "$TOKEN"   # refresh write creds
for i in 1 2 3; do docker buildx build --push . && break; sleep $((i*10)); done

Reduce layer size for 413

Split a giant single layer into smaller RUN/COPY steps.
Strip large intermediate files before the layer is committed.
Check the registry’s max blob/upload size limit.

How to prevent it

Mint write-scoped registry tokens in the same job that pushes.
Keep layers reasonably sized to stay under registry upload limits.
Wrap pushes in a bounded retry for transient registry 5xx.