Docker "USER nonexistent in image" build error in CI

By Daniel Zoghalchali·Latchkey

A USER instruction can only switch to an account that exists in the image. When the named user or group was never created with useradd/adduser (or the base image lacks it), the build fails or the container errors at start because the uid cannot be resolved.

What this error means

A build or container start fails with unable to find user <name> after a USER instruction. The account was never added to the image.

ERROR: failed to solve: unable to find user appuser: no matching entries in passwd file
# from: USER appuser

Common causes

The user was never created

A USER appuser without a prior useradd appuser references a nonexistent account.

The base image does not include the account

Minimal images (distroless, scratch) may not have the user you expect; switching to it fails.

How to fix it

Create the user before USER

1. Add the group and user, then switch to it.
2. Optionally use a numeric uid that always resolves.

RUN addgroup -S app && adduser -S app -G app
USER app

Use a numeric UID for minimal images

1. On distroless/scratch, reference a numeric uid that needs no passwd entry.

USER 1000:1000

How to prevent it

• Create users/groups before the USER instruction.
• Use numeric UIDs on minimal base images.
• Confirm the base image ships the account you reference.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation