How to fix COPY --from=builder: invalid from flag value builder: builder stage not found in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 153 views

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.

Quick fix

Fixes COPY --from=builder: invalid from flag value builder: builder stage not found

# Correct - defines a stage named 'builder'
FROM node:18-alpine AS builder

# Later in the file
COPY --from=builder /app/dist ./dist
  1. Verify the stage name exists and matches exactly
  2. Check for typos and case sensitivity
  3. Ensure stages are defined before they are referenced
  4. Use numeric index as an alternative (not recommended)
docker — error
# Correct - defines a stage named 'builder'
FROM node:18-alpine AS builder
# Later in the file
COPY --from=builder /app/dist ./dist
COPY --from=builder: invalid from flag value builder: builder stage not found

What this error means

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.

Typical symptoms

  • Docker build fails immediately with "invalid from flag value" error
  • Build stops before any actual compilation or installation steps run
  • Error message shows the exact stage name that could not be found
  • Multi-stage builds that previously worked fail after Dockerfile modifications

Common causes

  1. Stage name in COPY --from does not match any FROM ... AS name in the Dockerfile
  2. Typo or case mismatch between the stage definition (AS name) and reference (--from=name)
  3. The referenced stage was removed or renamed during Dockerfile refactoring
  4. Stage is defined after the COPY instruction that references it (stages must be defined in order)
  5. Missing AS keyword in the FROM instruction that should define the stage name
  6. Attempting to reference a stage by numeric index when it does not exist

How to fix "COPY --from=builder: invalid from flag value builder: builder stage not found"

1Verify the stage name exists and matches exactly

Check your Dockerfile for the FROM instruction that defines the stage. The AS keyword must be present:

dockerfile
# Correct - defines a stage named 'builder'
FROM node:18-alpine AS builder

# Later in the file
COPY --from=builder /app/dist ./dist

The name after AS must match exactly what you use in --from (including case).

2Check for typos and case sensitivity

Docker stage names are case-sensitive. These are all different stages:

dockerfile
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.

3Ensure stages are defined before they are referenced

Docker processes Dockerfiles top to bottom. A stage must be defined before you can copy from it:

dockerfile
# 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 ./binary
4Use numeric index as an alternative (not recommended)

If you cannot use named stages, you can reference by index (0-based):

dockerfile
FROM golang:1.21
RUN go build -o /app/binary .

FROM alpine
COPY --from=0 /app/binary ./binary

However, named stages are preferred because they are more maintainable and won't break if you reorder stages.

5Verify external image references

COPY --from can also reference external images directly:

dockerfile
# 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.

Advanced notes

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:

dockerfile
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/html

Platform-specific stages: In cross-platform builds with --platform, each platform builds independently. Stage names must be consistent across all target platforms.

Frequently asked questions

What does "COPY --from=builder: invalid from flag value builder: builder stage no" mean?
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.
How do I fix "COPY --from=builder: invalid from flag value builder: builder stage no"?
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.
What causes "COPY --from=builder: invalid from flag value builder: builder stage no"?
Stage name in COPY --from does not match any FROM ... AS name in the Dockerfile Typo or case mismatch between the stage definition (AS name) and reference (--from=name) The referenced stage was removed or renamed during Dockerfile refactoring
Is the "COPY --from=builder: invalid from flag value builder: builder stage no" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading