This error occurs when Docker cannot find a build stage referenced in a COPY --from instruction. The stage name must match exactly with an AS alias defined in a previous FROM instruction.
When Docker builds a multi-stage Dockerfile, it processes each FROM instruction as a separate build stage. The COPY --from flag allows you to copy files from a previous stage into the current one. This error means Docker cannot locate the stage you referenced. The build stage name in COPY --from must exactly match a name defined using the AS keyword in a previous FROM instruction. Docker is case-sensitive with stage names, so 'builder' and 'Builder' are treated as different stages. This error typically surfaces immediately during the docker build command when Docker parses the Dockerfile and validates stage references before executing any build steps.
Check your Dockerfile for the FROM instruction that defines the stage. The AS keyword must be present:
# Correct - defines a stage named 'builder'
FROM node:18-alpine AS builder
# Later in the file
COPY --from=builder /app/dist ./distThe name after AS must match exactly what you use in --from (including case).
Docker stage names are case-sensitive. These are all different stages:
FROM golang:1.21 AS builder # defines 'builder'
FROM golang:1.21 AS Builder # defines 'Builder' (different!)
FROM golang:1.21 AS BUILDER # defines 'BUILDER' (different!)Search your Dockerfile for all occurrences of the stage name and ensure they match exactly.
Docker processes Dockerfiles top to bottom. A stage must be defined before you can copy from it:
# WRONG - 'builder' is referenced before it exists
FROM alpine
COPY --from=builder /app/binary ./binary
FROM golang:1.21 AS builder
RUN go build -o /app/binary .
# CORRECT - 'builder' is defined first
FROM golang:1.21 AS builder
RUN go build -o /app/binary .
FROM alpine
COPY --from=builder /app/binary ./binaryIf you cannot use named stages, you can reference by index (0-based):
FROM golang:1.21
RUN go build -o /app/binary .
FROM alpine
COPY --from=0 /app/binary ./binaryHowever, named stages are preferred because they are more maintainable and won't break if you reorder stages.
COPY --from can also reference external images directly:
# Copy from an external image (not a build stage)
COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf
# Copy from a specific digest
COPY --from=alpine@sha256:abc123... /etc/alpine-release ./If referencing an external image, ensure the image name and tag are correct and accessible.
BuildKit behavior differences: With BuildKit enabled (default in Docker 23.0+), stage validation happens earlier and error messages may be more descriptive. Legacy builder may fail at different points.
Conditional stages with build arguments: When using ARG to conditionally select base images or stages, ensure all possible stage names are defined:
ARG BUILD_ENV=production
FROM node:18 AS builder-production
RUN npm run build:prod
FROM node:18 AS builder-development
RUN npm run build:dev
FROM nginx:alpine
ARG BUILD_ENV
COPY --from=builder-${BUILD_ENV} /app/dist /usr/share/nginx/htmlPlatform-specific stages: In cross-platform builds with --platform, each platform builds independently. Stage names must be consistent across all target platforms.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub