Docker build: 'failed to solve: no build stage in current context'

ERROR: failed to build: failed to solve: no build stage in current context means an instruction appears before the first FROM. The arrow in the error points at that line. Move it below FROM, or turn it into an ARG above FROM and declare it again inside the stage, as shown below.

In the case below an ENV line sat at the top of the file. Moving it one line down made the build pass.

The error

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 103B done
#1 DONE 0.3s
Dockerfile:1
--------------------
   1 | >>> ENV APP_HOME=/app
   2 |     FROM alpine:latest
   3 |     WORKDIR $APP_HOME
--------------------
ERROR: failed to build: failed to solve: no build stage in current context

Why it happens

A build stage starts at a FROM line, and an instruction such as ENV belongs to the stage it sits in. Written above the first FROM, it has no stage, and the build stopped while the Dockerfile was read: the output above has no load metadata step and no base image was touched. The build ended at step #1.

A line ends up there when settings are collected at the top of a file for readability, or a snippet is pasted above the base image. The excerpt in the error marks the line with >>>, so there is nothing to search for.

The message does not point at the base image, the registry or the build context. Nothing was pulled or sent, so checking your network, your login or the tag of the image is wasted time here; the fix is in the order of the lines and nowhere else.

The fix

FROM alpine:latest
ENV APP_HOME=/app
WORKDIR $APP_HOME
CMD ["sh"]

Built with docker build --progress=plain -t fix9-bld-c2 ., this version ended with exit code: 0. If you want the value at the top of the file, make it an ARG and declare it again inside the stage. This version also built, and its RUN pwd step printed /app:

ARG APP_HOME=/app
FROM alpine:latest
ARG APP_HOME
ENV APP_HOME=$APP_HOME
WORKDIR $APP_HOME
RUN pwd
CMD ["sh"]

How it was reproduced

A four-line Dockerfile on alpine:latest (image id 294b683cb724) whose first line was ENV APP_HOME=/app, built with docker build --progress=plain -t fix9-bld-c2 . on Docker Desktop for Windows, client and engine 29.9.3, buildx v0.38.1. The image name is the test's own.

Frequently asked

What does 'no build stage in current context' mean in Docker?

An instruction such as ENV, RUN or WORKDIR comes before the first FROM line. The error shows that line with >>>; move it below FROM.

Can ARG come before FROM in a Dockerfile?

Yes. In the test an ARG with a default above FROM built without an error; ENV in the same place gave 'no build stage in current context'.

How do I keep a setting at the top of a Dockerfile?

Make it an ARG above FROM, declare the same ARG again inside the stage and set ENV from it there, as in the fixed file in this post.

More decoded errors in the Fixes category. The rule that an ARG before FROM must be declared again inside the stage is shown with real output in UndefinedVar: Usage of undefined variable.