nginx in Docker warns that the user directive makes sense only for root
the "user" directive makes sense only if the master process runs with super-user privileges, ignoredShort answer
nginx logs this when its master process is not root: it ignores the user line and carries on, so the warning alone is harmless. If the container still stops, the real error is further down: nginx cannot write its pid file or temp folders as a non-root user. Remove the directive, move those paths to /tmp, or use the unprivileged image.
Fix it fast
1Find out which cause you have
Find out which user the container's main process runs as, then read the full startup log. The warning is the first line; the line after it is the real failure.
docker exec web id -u docker logs web 2>&1 | head -n 202Match what you see, then jump to its fix
- 1
The warning is printed once at startup and nginx keeps runningThe container runs as non-root but nginx.conf still has a user lineFix - 2
The log shows a permission error right after the warning, naming the pid file or a temp directoryThe container exits after the warning: pid file and temp folders are not writableFix - 3
Errors about /var/cache/nginx or /var/run when the container is started with --read-onlyA read-only container has nowhere to write cache and run filesFix
- 1
What does the error look like?
the "user" directive makes sense only if the master process runs with super-user privileges, ignored
Cause 1 of 3
The container runs as non-root but nginx.conf still has a user line
1Check
A user id other than 0 from the first step means the master process is not root. In the nginx source, this case only logs a warning and ignores the directive, then config parsing continues.
docker exec web grep -n '^user' /etc/nginx/nginx.conf2Fix
Delete or comment out the user line in the config you mount. A non-root master process cannot switch users anyway, so nothing is lost. The warning goes away.
# nginx.conf (top level)
# user nginx; <- remove this line
worker_processes auto;3Verify
Restart and check that the warning is gone.
docker restart web
docker logs web 2>&1 | grep -c 'super-user'Confirmed by raw.githubusercontent.com
Cause 2 of 3
The container exits after the warning: pid file and temp folders are not writable
1Check
The official image's default config writes outside the places a non-root user may write. The image documentation says a less privileged user needs a config that writes only to directories that user can access.
docker exec web grep -n -E 'pid|temp_path' /etc/nginx/nginx.conf2Fix
Mount a config that moves the pid file and the temp paths to /tmp (one temp path shown; move every temp path your config uses).
# nginx.conf
pid /tmp/nginx.pid;
http {
client_body_temp_path /tmp/client_temp;
}3Verify
Run it again and confirm the container stays up.
docker run -d --name web -v $PWD/nginx.conf:/etc/nginx/nginx.conf nginx
docker ps --filter name=webConfirmed by hub.docker.com
Cause 3 of 3
A read-only container has nowhere to write cache and run files
1Check
The image documentation says the default configuration needs write access to /var/cache/nginx and /var/run.
docker inspect web2Fix
Keep --read-only and mount writable volumes at those two paths.
docker run -d --read-only \
-v $(pwd)/nginx-cache:/var/cache/nginx \
-v $(pwd)/nginx-pid:/var/run \
nginx3Verify
The container stays in the running state.
docker ps --filter ancestor=nginxConfirmed by hub.docker.com
How do I stop it coming back?
- Pick one model and keep it: either a root master process with a user line, or a non-root one with no user line.
- If you need non-root, start from the unprivileged nginx image the Docker Hub page points to instead of patching the standard image.
- Keep the pid file and every temp path in /tmp when you run as non-root.
- Read docker logs from the first line; the warning is rarely the reason for an exit.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Servers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
Docker php image has no php.ini and my edits do not stay
A setting changed in php.ini inside the container is gone after the container is recreated
The official php image ships php.ini-development and php.ini-production but no active php.ini.
2 causes, each with a fixServers
The MinIO Console will not work behind an nginx proxy: no login, 403 on the WebSocket, or repeated disconnects
The Console UI shows repeated disconnects
Behind a proxy the MinIO Console needs three things.
4 causes, each with a fixServers
nginx returns 403 and logs directory index is forbidden
directory index of "/usr/share/nginx/html/" is forbidden
nginx got a request for a folder, found none of the index files it was told to look for, and listing the folder is off by default.
3 causes, each with a fixServers
nginx in a container returns 502 with 'connection refused' to another container
502 Bad Gateway
Inside a container, localhost is the container itself.
4 causes, each with a fixServers
The nginx container serves the default page or 404 because /usr/share/nginx/html has no app files
requests for your pages return 404 Not Found
The official nginx image serves whatever sits in /usr/share/nginx/html.
3 causes, each with a fix