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

By Kaveh Alemi·Latchkey

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

Diagnose it: build context, cache, or platform?

A Dockerfile that builds locally and fails in CI usually differs in one of three ways: the build context contains different files, the layer cache is cold or poisoned, or the runner architecture does not match what the base image provides.

Terminal

# what is actually being sent as build context (dockerignore applies)
docker build --no-cache --progress=plain -t probe . 2>&1 | head -40

# what platform are you on, and what does the base image support?
docker version --format '{{.Server.Arch}}'
docker buildx imagetools inspect <base-image> | grep -i platform

# prove it is not a cache artefact
docker build --no-cache .

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

Keep the build context small and deterministic

A missing .dockerignore sends node_modules, .git, and build output to the daemon, which is slow and can change layer hashes between environments.
A COPY of a path that exists locally but is gitignored will fail in CI, because the runner only has what the checkout produced.
Multi-arch builds need buildx and QEMU set up explicitly; a plain docker build on an ARM runner silently produces an ARM image.

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.

Frequently asked questions

What causes Docker "COPY --from" stage Index/Name does not exist in CI?

There are 3 common causes: the stage name does not match any from ... as, a numeric stage index is out of range, and copying from a stage defined below the copy. A COPY --from=builder with no FROM ...

How do I fix Docker "COPY --from" stage Index/Name does not exist in CI?

There are 2 fixes depending on which cause you have: name stages and reference them exactly and list the stages and order them correctly. Work through them in order, since the first is the most common.

What does Docker "COPY --from" stage Index/Name does not exist in CI actually mean?

The build fails on a COPY --from=...

How do I stop Docker "COPY --from" stage Index/Name does not exist in CI happening again?

Reference stages by stable names, not fragile numeric indexes. The prevention section lists 3 changes that keep it from recurring.