Docker "target stage could not be found" - Fix Multi-Stage Builds

You asked BuildKit to build (or copy from) a named stage that the Dockerfile does not define. The stage name in the command and the AS <name> in the file disagree.

What this error means

A build with --target <name>, or a COPY --from=<name>, fails with target stage "<name>" could not be found. The Dockerfile builds fine without the target.

docker build output

ERROR: failed to solve: target stage "prod" could not be found
# Dockerfile defines: FROM nginx AS production  (not "prod")

Common causes

Typo or mismatch in the stage name

The --target/--from value does not exactly match a FROM ... AS <name> in the Dockerfile (e.g. prod vs production).

The stage is not defined in this Dockerfile

You referenced a stage that exists in a different Dockerfile, or was renamed/removed, so it is absent from the one being built.

How to fix it

Match the target to a defined stage

Name stages explicitly and reference them by the exact same name.

Dockerfile / Terminal

FROM node:20 AS build
# ...
FROM nginx:alpine AS production
# build it:
docker build --target production -t api .

List the stages in the Dockerfile

Grep the stage names so the target is unambiguous.

Terminal

grep -niE '^FROM .* AS ' Dockerfile

How to prevent it

Keep stage names consistent between the Dockerfile and CI commands.
Reference stage names from a single variable where possible.
Lint for COPY --from references that name a non-existent stage.