🚨 Docker Error Guide: 'target stage could not be found' — Fix Multi-Stage Build Target Names

Overview

A multi-stage build fails because the stage name you asked BuildKit to build (or copy from) does not exist in the Dockerfile:

failed to solve: target stage "production" could not be found

Named stages are declared with FROM <image> AS <name>. When --target or COPY --from=<name> references a name that no stage declares — because of a typo, a renamed stage, or a case mismatch — BuildKit cannot resolve the target and aborts before building anything.

Symptoms

• docker build --target <name> fails instantly with target stage ... could not be found.
• A COPY --from=<name> step fails with the same message.
• The build works without --target but fails when you request a specific stage.
• The named stage exists but with different spelling or casing.

Common Root Causes

• Typo in the target name — --target prod when the stage is AS production.
• Stage was renamed or removed — the AS label changed but the CI command or COPY --from was not updated.
• Case mismatch — AS Build versus --target build (stage names are compared case-sensitively).
• Referencing an unnamed stage — the stage has no AS <name>, so it can only be referenced by numeric index.
• COPY --from pointing at a later stage — a stage can only copy from stages declared before it.
• Wrong Dockerfile — -f points at a file without that stage.

Diagnostic Workflow

List every stage name declared in the Dockerfile:

grep -nE '^FROM .* [Aa][Ss] ' Dockerfile

Print the file to see the full stage structure and ordering:

cat -n Dockerfile

Ask BuildKit to enumerate the build targets it can actually resolve:

docker buildx build --print=targets .

Build the intended stage explicitly and confirm the exact spelling:

docker build --target production -t myapp:1.4.2 .

If you use a non-default Dockerfile, verify the stage lives in the file you are building:

docker build -f docker/Dockerfile.prod --target production -t myapp:1.4.2 .

Example Root Cause Analysis

A release pipeline broke after a Dockerfile refactor:

failed to solve: target stage "production" could not be found

grep -nE '^FROM .* [Aa][Ss] ' Dockerfile returned:

2  FROM node:20 AS build
9  FROM nginx:1.27 AS prod

The Dockerfile had been tidied to rename production to prod, but the CI job still ran docker build --target production. Because no stage declared AS production, BuildKit could not find the target. Two valid fixes existed: update the CI command to --target prod, or rename the stage back to AS production. The team standardized on production across the Dockerfile and pipeline to avoid ambiguity. The takeaway: keep stage names in one canonical form and grep for them whenever a target fails.

Prevention Best Practices

• Use clear, stable stage names (build, test, production) and treat them as an interface — do not rename casually.
• Keep --target values in CI in sync with the Dockerfile; reference them from a shared variable where possible.
• Match case exactly between AS, --target, and COPY --from.
• Order stages so any COPY --from references a stage declared earlier in the file.
• Validate structure with docker buildx build --print=targets in CI to catch missing stages before a real build.

Quick Command Reference

grep -nE '^FROM .* [Aa][Ss] ' Dockerfile   # list declared stage names
docker buildx build --print=targets .      # enumerate resolvable targets
docker build --target production -t myapp:1.4.2 .
docker build -f docker/Dockerfile --target build -t myapp-build:1.4.2 .
cat -n Dockerfile                          # inspect stage ordering

Conclusion

target stage could not be found is a name-matching problem: the stage you asked for is not declared, or is declared under a different spelling or case. Grep the Dockerfile for FROM ... AS, compare it to your --target or COPY --from, and align them. Canonical stage names and a --print=targets check in CI keep multi-stage builds stable. More build guidance is in the Docker stack guides.