Improve error reporting and handling for missing build-secrets

[thaJeztah]

Description

I noticed this while writing up #1193 (comment)

Using this Dockerfile;

# syntax=docker/dockerfile:1

FROM alpine
RUN --mount=type=secret,id=SECRET_TOKEN,env=SECRET_TOKEN printenv SECRET_TOKEN

When building without the SECRET_TOKEN env-var set, an error is produced for a missing file;

docker build --no-cache --progress=plain --secret id=SECRET_TOKEN .
ERROR: failed to build: failed to stat SECRET_TOKEN: stat SECRET_TOKEN: no such file or directory

Exporting the env-var makes the problem go away;

SECRET_TOKEN=super-secret docker build --no-cache --progress=plain --secret id=SECRET_TOKEN .
#0 building with "desktop-linux" instance using docker driver
# ...
#10 DONE 0.9s

When explicitly specitying env as input for the secret, no error is produced in either case, and the build continues even though the env-var is not present;

docker build --no-cache --progress=plain --secret id=SECRET_TOKEN,env=SECRET_TOKEN .
#0 building with "desktop-linux" instance using docker driver
# ...
#10 DONE 0.9s

What I expected to see

For the first case, I'd expected the error message to include some information about the sources that were tried;

• env-var with the given ID (SECRET_TOKEN)
• file with the given ID as name (./SECRET_TOKEN)

For the second case, I'd expected the build to fail because the command-line argument explicitly set env as source for the secret;

• Produce an error if the env-var is not set
• It's OK to continue if the env-var is set, but empty (which may be a valid use-case).

Info

Reproduced on Docker Desktop with Docker v29.3.0 with containerd image-store enabled;

docker builder inspect
Name:          desktop-linux
Driver:        docker
Last Activity: 2025-07-02 11:29:21 +0000 UTC

Nodes:
Name:             desktop-linux
Endpoint:         desktop-linux
Status:           running
BuildKit version: v0.23.1
Platforms:        linux/arm64, linux/amd64, linux/amd64/v2, linux/riscv64, linux/ppc64le, linux/s390x, linux/386
Labels:
 org.mobyproject.buildkit.worker.containerd.namespace: moby
 org.mobyproject.buildkit.worker.containerd.uuid:      f1b49a59-81d0-436c-a1d4-ebb815a7ecaf
 org.mobyproject.buildkit.worker.executor:             containerd
 org.mobyproject.buildkit.worker.hostname:             docker-desktop
 org.mobyproject.buildkit.worker.moby.host-gateway-ip: 192.168.65.254
 org.mobyproject.buildkit.worker.network:              host
 org.mobyproject.buildkit.worker.selinux.enabled:      false
 org.mobyproject.buildkit.worker.snapshotter:          overlayfs
Devices:
 Name:                  docker.com/gpu=webgpu
 Automatically allowed: false
GC Policy rule#0:
 All:            false
 Filters:        type==source.local,type==exec.cachemount,type==source.git.checkout
 Keep Duration:  48h0m0s
 Max Used Space: 2.764GiB
GC Policy rule#1:
 All:            false
 Keep Duration:  1440h0m0s
 Reserved Space: 20GiB
GC Policy rule#2:
 All:            false
 Reserved Space: 20GiB
GC Policy rule#3:
 All:            true
 Reserved Space: 20GiB

[tonistiigi]

If you want to mark your secret as required you need to add ,required option to the definition. If you don't then passing the secret is optional.

[thaJeztah]

If that's the case, why does the first example produce an error?

ERROR: failed to build: failed to stat SECRET_TOKEN: stat SECRET_TOKEN: no such file or directory