Docker "could not find named context" - Fix --build-context in CI

A Dockerfile referenced a named build context (via COPY --from=<name> or FROM <name>) that the build never supplied. Named contexts must be passed with --build-context <name>=..., and BuildKit fails when one is missing.

What this error means

A docker buildx build fails with could not find named context <name>. The Dockerfile expects an extra context that the build invocation did not declare, so BuildKit cannot resolve the reference.

docker buildx output

ERROR: failed to solve: could not find named context "assets"
# Dockerfile: COPY --from=assets /dist /app
# but the build had no --build-context assets=...

Common causes

A named context was not passed to the build

Referencing --from=assets (a named context, not a build stage) requires --build-context assets=<dir|image|git-url>. Omitting it leaves the name unresolved.

Name mismatch between Dockerfile and --build-context

The name in --from=/FROM must exactly match the key in --build-context name=.... A typo makes the context "not found".

Named contexts require buildx/BuildKit

The --build-context flag is a buildx feature. Building through the legacy builder cannot supply named contexts at all.

How to fix it

Pass the named context with a matching name

Declare each named context the Dockerfile references.

Terminal

docker buildx build \
  --build-context assets=./dist \
  -t myorg/api:1.4.2 .

Confirm names line up (or use a stage instead)

Match the --from=/FROM name to the --build-context <name>= key exactly.
If you meant a multi-stage stage, define it with FROM ... AS <name> instead of a named context.
Use buildx (not the legacy builder) so --build-context is supported.

How to prevent it

Pass every named context the Dockerfile references via --build-context.
Keep context names identical between the Dockerfile and the build command.
Distinguish named contexts from build stages deliberately.