Analysis and Solution for COPY Instruction Stage Reference Errors in Docker Build

Problem Phenomenon and Error Analysis

During Docker build processes, developers frequently encounter error messages similar to the following:

failed to load cache key: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed

This error typically appears when executing the docker build command. While it superficially suggests permission issues or non-existent repositories, it may actually conceal deeper structural problems.

Dockerfile Multi-Stage Build Mechanism

Modern Dockerfiles extensively employ multi-stage build patterns. This design allows defining multiple build stages within a single Dockerfile, where each stage can be based on different base images. Ultimately, only necessary files are copied to the final image, significantly reducing image size.

In the provided case, the Dockerfile defines four build stages:

1. base stage: Based on ASP.NET Core runtime image
2. build stage: Based on .NET Core SDK image for compilation
3. debug stage: Inherits from build stage and performs publishing
4. final stage: Final production environment image

Root Cause: Incorrect Stage Reference

The core issue lies in this instruction within the final stage:

COPY --from=publish/app /app .

Two key misunderstandings exist here:

1. Incorrect Stage Name Reference

--from=publish/app attempts to reference a build stage named publish/app, but no such stage is defined in the current Dockerfile. When encountering this situation, the Docker builder attempts to interpret it as a remote image reference:

• First searches locally for a build stage named publish/app
• If not found, attempts to pull the docker.io/publish/app:latest image from Docker Hub
• Since this image doesn't exist on Docker Hub, permission error messages appear

2. Path Interpretation Error

The developer may have mistakenly thought publish/app was a filesystem path. However, in the COPY --from instruction, this parameter should reference previously defined build stage names, not filesystem paths.

Correct Solution

According to the build logic, published application files should be copied from the debug stage (or build stage). The correct instruction should be:

COPY --from=debug /app .

Alternatively, if copying directly from the compilation stage is desired:

COPY --from=build /app .

Deep Understanding of COPY --from Instruction

The COPY --from instruction plays a crucial role in multi-stage builds, with syntax:

COPY --from=<stage_name> <src> <dest>

Where:

• <stage_name>: Must be a build stage name previously defined in the current Dockerfile
• <src>: Source path, relative to the specified build stage's working directory
• <dest>: Destination path, relative to the current build stage's working directory

Debugging Techniques and Best Practices

1. Stage Naming Conventions

Use clear, meaningful names for build stages, avoiding strings that might be misinterpreted as image names. For example:

FROM mcr.microsoft.com/dotnet/core/sdk:3.1-buster AS builder
FROM mcr.microsoft.com/dotnet/core/aspnet:3.1-buster-slim AS runtime

2. Validate Stage References

When writing COPY --from instructions, ensure referenced stage names exactly match those defined in FROM ... AS <name>, including case sensitivity.

3. Use Intermediate Image Inspection

Temporarily modify the Dockerfile to add test commands at the end of each stage, verifying correct file generation:

FROM build as debug
RUN dotnet publish "App.Web.csproj" -c Debug -o /app
RUN ls -la /app  # Verify published files

4. Understand Error Messages

When seeing "pull access denied" errors, don't immediately assume permission issues. First check:

• Whether non-existent build stages are incorrectly referenced
• Whether stage names are misspelled
• Whether image names are accidentally used instead of stage names

Complete Corrected Dockerfile Example

# Base runtime stage
FROM mcr.microsoft.com/dotnet/core/aspnet:3.1-buster-slim AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

# Compilation stage
FROM mcr.microsoft.com/dotnet/core/sdk:3.1-buster AS build
WORKDIR /src
COPY ["src/App.Web/App.Web.csproj", "src/App.Web/"]
RUN dotnet restore "App.Web.csproj"
COPY . .
WORKDIR "/src/App.Web"
RUN dotnet build App.Web.csproj -c Debug -o /app

# Publishing stage
FROM build AS publish
RUN dotnet publish "App.Web.csproj" -c Debug -o /app

# Final stage
FROM base AS final
WORKDIR /app
COPY --from=publish /app .
ENTRYPOINT ["dotnet","App.Web.dll"]

Conclusion

Docker multi-stage builds are powerful tools for optimizing image sizes but require correct understanding of stage reference mechanisms. Incorrect stage name references in COPY --from instructions are common causes of "pull access denied" errors. By carefully checking stage definitions, ensuring name consistency, and understanding Docker builder mechanisms, such problems can be effectively avoided. In practical development, using descriptive names for each build stage and adding verification commands at critical steps is recommended to ensure build process correctness.