dockerfile: reject --chown by name with --link at parse time - #7134

Problem

COPY --link --chown=<user>[:<group>] with a non-numeric user or group is accepted by the Dockerfile frontend, but on any worker that supports MergeOp the build fails late in the solver with

failed to solve: invalid user index: -1

Nothing in that message points at --chown, so people end up either dropping --link or hard-coding UIDs after a lot of trial and error (see the issue thread and the linked buildx issues). Only numeric --chown=UID[:GID] (and root) work with --link.

Root cause

• frontend/dockerfile/dockerfile2llb/convert_copy.go:54-56: llb.WithUser(cfg.chown) is added unconditionally. WithUser (client/llb/fileop.go:231) turns anything that is not an integer or root into a UserOpt{Name: ...}, which marshals as a pb.UserOpt_ByName whose Input is the FileOp base index.
• frontend/dockerfile/dockerfile2llb/convert_copy.go:334-349: when --link is set, --chmod is empty and the worker supports CapMergeOp, the FileOp is executed on llb.Scratch() and the result is merged on top of the stage. The base of that FileOp is pb.Empty (-1), so the marshalled owner is byName:{name:"foo" input:-1} (verified by marshalling the frontend output in a unit test).
• solver/llbsolver/ops/file.go:289 and :534 reject ByName.Input < 0 with invalid user index.

Workers without MergeOp never take this path: they fall back to a regular d.state.File(...) copy where names resolve against the stage's /etc/passwd, which is why the classic graphdriver backend of the docker driver is unaffected. docker build with the containerd image store enables MergeOp and takes the same path.

Fix

In dispatchCopy, whenever --link is set, reject a --chown that refers to a user or group by name with an error that names the flag and the remedy:

--chown=foo:bar: user and group names can't be resolved when used with --link, use numeric uid[:gid] instead

The check reuses llb.WithUser to decide what counts as "by name", so it can never disagree with how the value is actually marshalled (root and numeric IDs still pass). It does not look at opt.llbCaps or at the --chmod fallback: a Dockerfile with --link --chown=<name> is rejected the same way on every worker, instead of depending on which copy path the current daemon takes (review feedback). The --chown section of frontend/dockerfile/docs/reference.md now states the restriction.

No new linter rule: the build would fail anyway on this path, so a hard error at frontend time is strictly more informative than a warning followed by the solver error.

How tested

New unit test TestCopyLinkChownByName in frontend/dockerfile/dockerfile2llb/convert_test.go (no daemon needed; it enables CapMergeOp via pb.Caps.CapSet(pb.Caps.All())).

Before the fix:

--- FAIL: TestCopyLinkChownByName (0.00s)
    --- FAIL: TestCopyLinkChownByName/user_and_group_names (0.00s)
        convert_test.go:502: Error: An error is expected but got nil.
    --- FAIL: TestCopyLinkChownByName/user_name (0.00s)
        convert_test.go:502: Error: An error is expected but got nil.
    --- FAIL: TestCopyLinkChownByName/group_name (0.00s)
        convert_test.go:502: Error: An error is expected but got nil.
FAIL	github.com/moby/buildkit/frontend/dockerfile/dockerfile2llb	0.012s

Marshalling the frontend output for FROM scratch / COPY --link --chown=foo:bar a /b before the fix showed the FileOp copy owner as user=byName:{name:"foo" input:-1} group=byName:{name:"bar" input:-1}, i.e. exactly what the solver rejects.

After the fix:

--- PASS: TestCopyLinkChownByName (0.00s)
    --- PASS: TestCopyLinkChownByName/numeric (0.00s)
    --- PASS: TestCopyLinkChownByName/root (0.00s)
    --- PASS: TestCopyLinkChownByName/user_name (0.00s)
    --- PASS: TestCopyLinkChownByName/user_and_group_names (0.00s)
    --- PASS: TestCopyLinkChownByName/group_name (0.00s)
    --- PASS: TestCopyLinkChownByName/user_name_without_merge_op (0.00s)
    --- PASS: TestCopyLinkChownByName/user_name_with_chmod (0.00s)
    --- PASS: TestCopyLinkChownByName/user_name_without_link (0.00s)
ok  	github.com/moby/buildkit/frontend/dockerfile/dockerfile2llb	0.869s

Also: go test ./frontend/dockerfile/dockerfile2llb/ ./frontend/dockerfile/instructions/ pass, gofmt -l clean, go vet clean, golangci-lint run ./frontend/dockerfile/dockerfile2llb/ reports 0 issues, go build ./frontend/dockerfile/... ./cmd/... succeeds.

Links

• Related: COPY --link not compatible with chown #2987 (this PR makes the failure explicit and documents it; it does not implement resolving names against the base image, so it does not close the issue)
• Related: buildx failed with: ERROR: failed to solve: invalid user index: -1 docker/buildx#1408, COPY --link --chown=user (Fails with "failed to solve: invalid user index: -1") docker/buildx#1526, docs: proposal to raise awareness about an unexpected behavior of COPY --link #4964
• Docs: https://docs.docker.com/reference/dockerfile/#copy---chown---chmod

This change was prepared with an AI agent operated by KR-Ravindra, who reviewed and tested it.