Maaz Zindani

Loading the index…

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

Docker build or container cannot create a directory: permission denied

Errormkdir: cannot create directory '/app/data': Permission denied

Short answer

Once USER switches to a non-root account, every later RUN and the container itself run as that account. It cannot write into folders that root created. Make and chown the folders while still root, copy files with COPY --chown, and put USER after that. Do not add sudo to the image.

  • Applies to Docker Engine 27, Dockerfile syntax 1.x, python:3.13-slim image
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out who the process runs as and who owns the folder it fails on. A mismatch between the two is the whole problem.

    docker run --rm my-image id
    docker run --rm my-image ls -ld /app /app/data
  2. 2Match what you see, then jump to its fix

    1. 1mkdir: cannot create directory ... Permission denied during docker build, right after a USER lineThe directory is created or written after USER, in a root-owned parentFix
    2. 2PermissionError: [Errno 13] when the app writes next to files that came from COPYFiles were copied in as rootFix
    3. 3sudo: command not found, or a Dockerfile that sets USER root at the endThe fix was sudo or running everything as rootFix

What does the error look like?

  • mkdir: cannot create directory '/app/data': Permission denied
  • PermissionError: [Errno 13] Permission denied: '/app/output.csv'

Cause 1 of 3

The directory is created or written after USER, in a root-owned parent

1Check

USER sets the default user for the rest of the build stage, and RUN instructions and the container's CMD and ENTRYPOINT use it. A parent such as / or /opt belongs to root, so that user cannot add anything to it.

grep -n -E '^(USER|WORKDIR|RUN mkdir|COPY)' Dockerfile

2Fix

Do the privileged setup first, while the build still runs as root: create the account, create the folder, hand it over, and only then switch.

RUN groupadd -r app && useradd --no-log-init -r -g app app \
    && mkdir -p /app/data \
    && chown -R app:app /app
USER app
WORKDIR /app

3Verify

The container can write where it failed before.

docker run --rm my-image sh -c 'touch /app/data/test && echo ok'

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

Files were copied in as root

1Check

Without --chown, COPY creates files with UID and GID 0, which is root. A non-root app may read them but not modify them or add files beside them.

docker run --rm my-image ls -ln /app

2Fix

Set the owner on the copy, using the name you created or a numeric ID. Names must already exist in the image's /etc/passwd and /etc/group, or the build fails.

COPY --chown=app:app . /app

3Verify

Owner column shows the app user, not 0.

docker run --rm my-image ls -ln /app

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The fix was sudo or running everything as root

1Check

The build guide advises against sudo in images because it causes TTY and signal-forwarding problems, and says to use USER for services that do not need privileges.

grep -n -E 'sudo|USER root' Dockerfile

2Fix

Remove sudo. Do root-only work in earlier RUN lines, then switch with USER once, with an explicit UID and GID if the host must match.

RUN groupadd -r -g 10001 app && useradd --no-log-init -r -u 10001 -g app app
USER 10001:10001

3Verify

The container runs as the numeric user.

docker run --rm my-image id -u

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Order the Dockerfile: install packages, create the user, create and chown folders, COPY --chown, then USER.
  • Give the app user an explicit UID and GID so rebuilds and host mounts stay predictable.
  • Keep writable data in one folder and own only that folder.
  • Switch USER as few times as possible; each switch makes the file harder to reason about.

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.