docker run says it cannot find the user in the passwd file
docker: Error response from daemon: linux spec user: unable to find user myuser: no matching entries in passwd fileShort 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.
Fix it fast
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/passwd2Match what you see, then jump to its fix
- 1
The 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
The 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
The 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
- 1
What does the error look like?
docker: Error response from daemon: linux spec user: unable to find user myuser: no matching entries in passwd fileno 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 -g2Fix
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 id3Verify
The command now starts and prints the numeric IDs you passed.
docker run --rm --user 1000:1000 IMAGE idConfirmed by raw.githubusercontent.com
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))" Dockerfile2Fix
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 appuser3Verify
Rebuild and print the user the container runs as.
docker build -t my-app .
docker run --rm my-app idConfirmed by docs.docker.com
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/passwd2Fix
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:100013Verify
Run the image and confirm it starts under that user.
docker run --rm IMAGEConfirmed by raw.githubusercontent.com
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
Servers
Docker build or container cannot create a directory: permission denied
PermissionError: [Errno 13] Permission denied: '/app/output.csv'
Once USER switches to a non-root account, every later RUN and the container itself run as that account.
3 causes, each with a fixServers
usermod cannot add your user to the docker group, or it seems to have no effect
id does not list docker after the command succeeded
Create the group if it is missing, then add your user with usermod -aG docker.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fix