Maaz Zindani

Loading the index…

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

EACCES permission denied when a container creates node_modules/.cache

ErrorError: EACCES: permission denied, mkdir '/usr/app/node_modules/.cache'

Short answer

The container user cannot write inside node_modules because the folder is owned by root. This happens when Docker creates a volume mount point as root, or when an old volume was filled by a root build. Create the folder in the Dockerfile with the right owner, then remove the stale volume.

  • Applies to Docker Engine 27, Docker Compose 2.x, Node.js 22, create-react-app 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the user the container runs as with the owner of node_modules. If they differ, the causes below apply.

    docker compose run --rm app sh -c 'id -u; ls -ld /usr/app/node_modules'
  2. 2Match what you see, then jump to its fix

    1. 1ls -ld shows root root on node_modules and id -u prints a number other than 0node_modules is owned by root while the app runs as a normal userFix
    2. 2The Dockerfile now sets the right owner, but the error staysAn old volume on node_modules was filled when the image ran as rootFix

What does the error look like?

  • Error: EACCES: permission denied, mkdir '/usr/app/node_modules/.cache'
  • The dev server exits right after start when node_modules is a Compose volume

Cause 1 of 2

node_modules is owned by root while the app runs as a normal user

1Check

Without --chown, COPY creates files owned by UID 0. The USER instruction then switches the rest of the build and the runtime to another user, who cannot write there.

docker compose run --rm app ls -ln /usr/app

2Fix

Create the cache folder while still root, give it to the runtime user, and only then switch user. Use COPY --chown for the files you copy.

FROM node:22
WORKDIR /usr/app
COPY --chown=node:node package*.json ./
RUN npm ci
RUN mkdir -p node_modules/.cache && chown -R node:node node_modules
COPY --chown=node:node . .
USER node

3Verify

Rebuild, then create the folder as the runtime user.

docker compose build && docker compose run --rm app sh -c 'mkdir -p node_modules/.cache && echo writable'

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 2

An old volume on node_modules was filled when the image ran as root

1Check

A volume is filled from the image only while it is empty. After that it keeps its files, and their owner, and the image's files at that path are obscured.

docker volume ls
docker compose run --rm app ls -ld /usr/app/node_modules

2Fix

Remove the project's volumes so the next start fills a fresh one from the corrected image.

docker compose down --volumes
docker compose up --build

3Verify

node_modules and its cache folder now belong to the runtime user.

docker compose run --rm app ls -ld /usr/app/node_modules /usr/app/node_modules/.cache

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Use COPY --chown and USER together in every Dockerfile that runs as a non-root user.
  • Do not run the dev container as root just to silence the error; fix the owner instead.
  • After changing the Dockerfile user, run docker compose down --volumes once so no old volume keeps root-owned files.

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.