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.
Frequently asked questions
What causes ""failed commit on ref""?
A transient 500/503 from the registry while finalizing a blob or manifest. This is server-side and usually clears on retry.
How do I fix "failed commit on ref"?
Distinguish a transient 5xx from an auth failure by the status code.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
