Docker "COPY --chown ... invalid user" - Fix Unknown User/Group in Builds

A COPY --chown (or RUN chown) named a user or group that does not exist in the image at that point. The build cannot resolve the name to a uid/gid, so it fails.

What this error means

The build fails on a COPY --chown=... or RUN chown ... step with invalid user or unable to find user. The name is correct but the account was never created in the image, or is created in a later layer.

failed to solve: lchown /app: invalid argument
# or:
COPY --chown=appuser:appuser ... : unable to find user appuser:
no matching entries in passwd file

Common causes

The user/group is never created in the image

The base image has no appuser, and no useradd/adduser step adds one, so chown cannot resolve the name.

chown runs before the user is created

Docker layers are ordered. A COPY --chown=appuser placed above the RUN adduser appuser line references a user that does not exist yet in that layer.

Wrong name vs numeric id assumption

Some minimal images only have numeric ids, not named entries in /etc/passwd. A named --chown then fails where a numeric --chown=1000:1000 would work.

How to fix it

Create the user before chowning to it

Add the account in an earlier layer than any COPY/RUN that references it.

RUN addgroup -S appuser && adduser -S appuser -G appuser
COPY --chown=appuser:appuser . /app

Use numeric uid/gid on minimal images

When the base lacks named users, chown by number.

COPY --chown=1000:1000 . /app

How to prevent it

• Create users/groups before any instruction that references them.
• Prefer numeric uid/gid on minimal or distroless base images.
• Keep user creation near the top of the relevant build stage.

Related guides