Docker "stage name not found" multi-stage build error in CI

A COPY --from=<name> (or FROM <name>) must reference a stage that was already declared with FROM ... AS <name> earlier in the file. A misspelled name, or a stage defined later, leaves BuildKit with no such stage to copy from.

What this error means

A build fails with an invalid --from flag or unknown stage error at a COPY --from=. The referenced stage name does not match any earlier AS declaration.

ERROR: failed to solve: invalid from flag value builder: stage "builder" could not be found
# from: COPY --from=builder /app/bin /app/bin

Common causes

A misspelled stage name

The AS build declaration and the --from=builder reference do not match.

The stage is declared after the COPY

Stages must be defined before they are referenced; a later FROM ... AS x is not visible to an earlier COPY.

How to fix it

Match the stage name exactly

1. Use the same identifier in AS and --from.
2. Keep stage names lowercase and consistent.

FROM golang AS build
RUN go build -o /app/bin ./...
FROM alpine
COPY --from=build /app/bin /app/bin

Declare the stage before referencing it

1. Order stages so any referenced stage appears earlier in the file.

FROM node AS deps
# ...
FROM node AS app
COPY --from=deps /node_modules ./node_modules

How to prevent it

• Keep AS names and --from references identical.
• Declare stages before any reference to them.
• Lint multi-stage Dockerfiles with hadolint.

Related guides