Maaz Zindani

Loading the index…

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

nginx in Docker warns that the user directive makes sense only for root

Errorthe "user" directive makes sense only if the master process runs with super-user privileges, ignored

Short 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.

  • Applies to nginx 1.27, Docker Engine 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 20
  2. 2Match what you see, then jump to its fix

    1. 1The warning is printed once at startup and nginx keeps runningThe container runs as non-root but nginx.conf still has a user lineFix
    2. 2The 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. 3Errors 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

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.conf

2Fix

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

Did this fix it?

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.conf

2Fix

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=web

Confirmed by hub.docker.com

Did this fix it?

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 web

2Fix

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 \
  nginx

3Verify

The container stays in the running state.

docker ps --filter ancestor=nginx

Confirmed by hub.docker.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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