Docker COPY --from misspelled stage name is misreported as a registry pull error

A misspelled or renamed stage name in a Docker COPY --from instruction is not flagged as a stage error by BuildKit. Instead, BuildKit treats the name as an image reference and attempts a registry pull, producing an authorization-style failure. Numeric stage indexes behave differently and produce clearer errors, though they can silently point to the wrong stage after edits. Typical causes include renames that missed a caller, stages referenced from a different Dockerfile, and shifted indexes. The author recommends checking for a stage-name suggestion in the error message first and using named stages to avoid index drift.