Check registry-cache import separately from Docker build success

Bottom line: Investigate the cache step when a successful build unexpectedly does all its work again. Keep image completion, cache import and cache export as separate results rather than assuming that one successful exit establishes every acceleration step.

Source fact: documented behavior

The Registry cache documentation is the primary reference.

The registry cache backend stores its cache separately from the resulting image. Its cache ref must differ from the target location used to push the output image; separate tags, image names or repositories are documented choices. When the --cache-from target does not exist, the cache import fails but the build continues.

What the source does not establish

This article addresses a missing registry-cache import alongside a continuing build. It does not prove cache validity, choose a retention policy or prescribe branch-overwrite behavior from another backend guide. Confirm builder and registry support independently. Keep reproducibility, secret handling and release-artifact acceptance separate from whether cached work was available.

Applicability questions

• Which exact cache reference does the build try to import?
• Does that reference differ from the output image target?
• What evidence shows import, export and build outcomes separately?
• Which approved comparison can distinguish a cold run from the intended warm run?

DSE recommendation: preserve the cache-step outcome

DSE recommends recording registry-cache import and export outcomes separately from the image-build result.

Capture the sanitized managed invocation and identify its selected builder. Write the output image target and cache import/export references in different fields. Have the build owner confirm the intended registry location and the approved access arrangement. Resolve a missing or mistyped cache reference before changing source instructions to explain an unexpectedly slow build.

Inspect the actual build record for the cache import outcome. Keep an absent target visible even if the final image was produced. Record whether the run intentionally started without external cache or whether persistence was expected. Do not turn a successful overall job into evidence that a previous job exported the artifact this one requested.

Review the export stage independently when the cache should be available to later runs. Retain its target and actual outcome with the build identity. Have the registry owner investigate an inaccessible or unexpectedly absent object through the approved procedure. Avoid pointing the cache reference at the output image merely to obtain an existing tag.

Define the intended comparison before drawing a performance conclusion. Use the same harmless source revision and material build inputs, and record relevant builder or cache-state differences. Keep an acceptable final image and an acceptable cache workflow as separate release observations rather than withholding one simply because the other needs investigation.

Verification and evidence

Proposed verification, not performed: use a disposable registry location and an approved supported builder. Prepare a deliberately nonexistent cache reference as one labeled fixture, predict that import failure and retain the actual build and cache-step outcomes.

For a separate authorized case, export to the approved distinct cache reference and repeat the representative build using that reference. Inspect actual import/export results and the build record instead of assuming a timing improvement proves a cache hit. Retain source revision, sanitized invocation, references, cache outcomes and artifact result. No build duration, cache availability or acceleration result has been measured for this article.

Official references

• Registry cache — Docker Docs.

Source review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.