Docker "COPY --from" Stage Index/Name Does Not Exist in CI

A COPY --from=<stage> referenced a build stage that does not exist - a numeric index past the last stage, or a name that no FROM ... AS defines. Unlike a missing source file, the stage reference itself is invalid.

What this error means

The build fails on a COPY --from=... step with invalid from flag value or a "stage not found" message. The named/indexed stage is simply absent from this Dockerfile, so BuildKit has nothing to copy from.

docker build output

ERROR: failed to solve: invalid from flag value builder: stage "builder" not found
# or by index past the last stage:
ERROR: failed to solve: COPY --from=3 ...: invalid from flag value 3

Common causes

The stage name does not match any FROM ... AS

A COPY --from=builder with no FROM ... AS builder in the file fails. A rename, a typo, or copying from a stage defined in a different Dockerfile all trigger it.

A numeric stage index is out of range

COPY --from=2 refers to the third stage (0-indexed). If the build has fewer stages, the index is invalid.

Copying from a stage defined below the COPY

A stage referenced by --from must be defined earlier in the Dockerfile; referencing one declared later is not resolved.

How to fix it

Name stages and reference them exactly

Give each stage a stable AS name and copy from that name.

Dockerfile

FROM golang:1.22 AS builder
RUN go build -o /app ./...

FROM gcr.io/distroless/static
COPY --from=builder /app /app

List the stages and order them correctly

Confirm the stage exists and is declared before the COPY that uses it.

Terminal

grep -niE '^FROM .* AS |^COPY --from=' Dockerfile

How to prevent it

Reference stages by stable names, not fragile numeric indexes.
Define a stage before any COPY --from that uses it.
Lint for COPY --from references that name a non-existent stage.