Maaz Zindani

Loading the index…

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

nginx fails on OpenShift with mkdir() client_temp failed (13: Permission denied)

Errornginx: [emerg] mkdir() "/var/cache/nginx/client_temp" failed (13: Permission denied)

Short answer

OpenShift starts the container under a random user ID that belongs to the root group, whatever USER your image sets. nginx then cannot create its temp directories in paths owned by another user. Give group 0 read and write access to those paths, move them, and listen on a port above 1024.

  • Applies to OpenShift 4.x, nginx 1.2x, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find which user ID the pod really runs as, and read the owner and mode of the directory in the error.

    oc rsh my-pod id
    oc rsh my-pod ls -ld /var/cache/nginx
  2. 2Match what you see, then jump to its fix

    1. 1id shows a uid you did not choose and gid=0(root), and ls shows another owner without group write.The directory is not writable by group 0Fix
    2. 2The error names a temp directory under /var/cache/nginx, and you prefer to keep that tree read-only.nginx still tries to write to a path you can moveFix
    3. 3After the permission error is gone, nginx fails to bind or the pod restarts.nginx listens on port 80, which needs rootFix

What does the error look like?

  • nginx: [emerg] mkdir() "/var/cache/nginx/client_temp" failed (13: Permission denied)

Cause 1 of 3

The directory is not writable by group 0

1Check

OpenShift assigns an arbitrary UID from the project's range and puts it in the root group (GID 0). That UID can write only to paths that group 0 may write.

oc rsh my-pod ls -ld /var/cache/nginx /var/run

2Fix

In the Dockerfile, give group 0 the same access as the owner on every path nginx writes to.

RUN chgrp -R 0 /var/cache/nginx /var/run && \
    chmod -R g=u /var/cache/nginx /var/run

3Verify

Rebuild, redeploy and read the pod log.

oc logs my-pod

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

nginx still tries to write to a path you can move

1Check

client_body_temp_path sets the directory that holds temporary files for client request bodies; its default is client_body_temp relative to the nginx prefix.

grep -rn temp_path /etc/nginx/

2Fix

Point the temp path at a directory that group 0 can write, such as /tmp, in nginx.conf.

http {
    client_body_temp_path /tmp/client_temp;
}

3Verify

Test the config inside the image, then redeploy.

nginx -t

Confirmed by nginx.org

Did this fix it?

Cause 3 of 3

nginx listens on port 80, which needs root

1Check

Ports lower than 1024 require root privileges, and OpenShift does not run the container as root.

grep -rn "listen" /etc/nginx/conf.d/

2Fix

Listen on 8080 inside the container and let the Service map port 80 to it.

server {
    listen 8080;
}

3Verify

The pod becomes Ready.

oc get pods

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Write the chgrp -R 0 and chmod -R g=u lines into every image that is meant for OpenShift.
  • Do not depend on the USER directive; the platform can replace it with an arbitrary user ID.
  • Keep writable paths in as few places as possible, such as /tmp, so the Dockerfile has less to fix.

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.