Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker run says it cannot find the user in the passwd file

Errordocker: Error response from daemon: linux spec user: unable to find user myuser: no matching entries in passwd file

Short answer

Docker looks up a user name in the /etc/passwd file inside the image, not on your host. The error means that name is not there, or the image has no passwd file at all. Create the user in the Dockerfile, or pass a numeric UID:GID, which Docker does not look up.

  • Applies to Docker Engine 28, Dockerfile reference, Debian and Ubuntu base images
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the passwd file of the image, without starting your own command, and look for the name you passed. If it is missing, the causes below apply.

    docker run --rm --entrypoint cat IMAGE /etc/passwd
  2. 2Match what you see, then jump to its fix

    1. 1The failing command has -u, --user or a USER line with a name such as myuser or jenkins, and that name is not in the output of the first step.The user name only exists on your host or in a CI agentFix
    2. 2The image builds, but docker run fails at start with the error, and the Dockerfile has a line like USER appuser.The Dockerfile uses USER with a name it never createdFix
    3. 3The base image is scratch or a very small image, and any user name you pass fails.The image has no /etc/passwd file to look inFix

What does the error look like?

  • docker: Error response from daemon: linux spec user: unable to find user myuser: no matching entries in passwd file
  • no matching entries in passwd file

Cause 1 of 3

The user name only exists on your host or in a CI agent

1Check

User names are resolved from the passwd file inside the container image. A user that exists on your laptop or on the build agent does not exist in the image.

docker run --rm --user myuser IMAGE id
id -u && id -g

2Fix

Give Docker the numbers instead of the name. A numeric user or group is not looked up in passwd, so it works for any image.

docker run --rm --user "$(id -u):$(id -g)" IMAGE id

3Verify

The command now starts and prints the numeric IDs you passed.

docker run --rm --user 1000:1000 IMAGE id

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

The Dockerfile uses USER with a name it never created

1Check

Search the Dockerfile for the line that creates the account. USER only switches to an account, it does not make one.

grep -n -E "^(USER|RUN .*(useradd|groupadd|adduser|addgroup))" Dockerfile

2Fix

Create the group and user in an earlier RUN step, with an explicit UID and GID, then switch to it. This example is for Debian and Ubuntu images; Alpine images use addgroup and adduser instead.

RUN groupadd --gid 10001 appuser \
 && useradd --no-log-init --uid 10001 --gid appuser appuser
USER appuser

3Verify

Rebuild and print the user the container runs as.

docker build -t my-app .
docker run --rm my-app id

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The image has no /etc/passwd file to look in

1Check

The lookup reads /etc/passwd inside the image. If the file does not exist, a name lookup returns an error. The first step command also fails with a cat error.

docker run --rm --entrypoint ls IMAGE -l /etc/passwd

2Fix

Use a numeric UID:GID in USER or --user. If you need names, copy a passwd file from a build stage that has one.

FROM scratch
COPY --from=build /etc/passwd /etc/passwd
USER 10001:10001

3Verify

Run the image and confirm it starts under that user.

docker run --rm IMAGE

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Use numeric UID:GID values in Dockerfiles and run commands when the image is built by one team and run by another.
  • Create the account in the same Dockerfile that has the USER line, and rebuild when you rename it.
  • Pass the host user as "$(id -u):$(id -g)" in CI scripts, not as a name.
  • Set an explicit UID and GID, so file ownership on mounted folders does not change between rebuilds.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.