docker: Error response from daemon: unable to find user appuser: no matching entries in passwd file means the image has no user with that name. A name passed to --user must exist in the image's /etc/passwd; a numeric user ID does not have to. Pass a UID such as --user 1000:1000, or create the user in the image.

The user names on your machine, or in another image, do not count: only the image the container starts from is consulted.

The error

PS> docker run --rm --name fix8-cli-u1 --user appuser alpine id
docker: Error response from daemon: unable to find user appuser: no matching entries in passwd file

Run 'docker run --help' for more information

Why it happens

A process in a Linux container runs as a numeric UID and GID. When you give a name, the engine looks it up in the image's /etc/passwd to find the numbers, and alpine has no appuser. Run without --rm, the container was created but never started: docker ps -a listed it as Created. The exit code was 125, Docker's own failure, not one from the id command.

So a --user name that works with one image fails with another that never created that user: alpine has guest (shown below) but no appuser.

The fix

Use numbers; they need no entry in /etc/passwd:

PS> docker run --rm --name fix8-cli-u1 --user 1000:1000 alpine id
uid=1000 gid=1000 groups=1000

Or use a name that the image does have. alpine ships a guest user:

PS> docker run --rm --name fix8-cli-u1 --user guest alpine id
uid=405(guest) gid=100(users) groups=100(users)

The UID run has no name next to the number, because the image has no entry for 1000; the guest run shows both. To check a name before you use it, search the image's passwd file; only guest came back: 

PS> docker run --rm --name fix8-cli-u2 alpine grep -E "guest|appuser" /etc/passwd
guest:x:405:100:guest:/dev/null:/sbin/nologin

For your own images, the name you pass must be created in the image itself; a user that exists only on your machine does not help.

How it was reproduced

Docker Desktop on Windows 11, client and engine 29.9.2, Windows PowerShell 5.1, the cached alpine:latest image. docker run --user appuser alpine id gave the message above with exit code 125 (PowerShell printed the blank line in the message as System.Management.Automation.RemoteException; it is shown empty here). The numeric UID and the guest user both ran id. The container name is the test's own.

Frequently asked

Why does docker run --user say no matching entries in passwd file?
The user name does not exist in the image's /etc/passwd. Use a numeric UID and GID such as --user 1000:1000, or create the user in the image.
Can I run a Docker container as a UID that does not exist in the image?
Yes. In this test --user 1000:1000 ran on alpine, which has no user 1000; id printed the numbers with no name.
How do I list the users in a Docker image?
Print the image's passwd file with docker run --rm alpine cat /etc/passwd (put your image in place of alpine). For alpine it listed 17 users, among them root, nobody and guest, and no appuser.

More decoded errors in the Fixes category. A daemon error with a format problem in the image name is covered in invalid reference format.