moby / moby/buildkit

Dockerfile: improve error message when using instructions before first "FROM"

Open
#2,115 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/dockerfile area/ux kind/enhancement
Dominant language
Go
Stars
10.3k
Forks
1.5k
Avg merge
1d 21h
Merged PRs (30d)
50

Description

Relates to https://github.com/docker/buildx/issues/426#issuecomment-819457197

The Dockerfile syntax only allows ARG to be specified before the first FROM. If a user accidentally puts any other Dockerfile instruction before the first FROM, a confusing error message is produced.

For example:

docker build -<<EOF
MAINTAINER foobar
FROM busybox
EOF

Produces:

[+] Building 0.1s (2/2) FINISHED
 => [internal] load build definition from Dockerfile                        0.0s
 => => transferring dockerfile: 70B                                         0.0s
 => [internal] load .dockerignore                                           0.0s
 => => transferring context: 2B                                             0.0s
failed to solve with frontend dockerfile.v0: failed to create LLB definition: no build stage in current context

Note that the error is equally "bad" on the classic builder (but less "noise");

DOCKER_BUILDKIT=0 docker build -<<EOF
MAINTAINER foobar
FROM busybox
EOF
Sending build context to Docker daemon  2.048kB
Error response from daemon: no build stage in current context

This error message could be improved to be more descriptive:

  • mention that an instruction was used before the first FROM, but not allowed
  • include the instruction in the error? (probably not needed if the new "rich" errors are used (with buildx))

More in general, perhaps we should include a link to the documentation, which could be a /go/ redirect (as permalink), e.g. https://docs.docker.com/go/dockerfile/ or https://docs.docker.com/go/dockerfile-syntax/

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the BuildKit and classic-builder examples in the issue, then trace validation of Dockerfile instructions before the first FROM. Done means an invalid pre-FROM instruction produces a descriptive error that explains the ordering rule, with the documentation-link decision resolved.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, go
Domain
build-system
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.