EACCES permission denied when a container creates node_modules/.cache
Error: 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.
Fix it fast
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'2Match what you see, then jump to its fix
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/app2Fix
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 node3Verify
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
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_modules2Fix
Remove the project's volumes so the next start fills a fresh one from the corrected image.
docker compose down --volumes
docker compose up --build3Verify
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/.cacheConfirmed by docs.docker.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Servers
Node.js app says Cannot find module only when it runs under Docker Compose
The same image starts fine with docker run but fails with docker compose up
The image installed node_modules, but a Compose volume mounted over the app folder hides them.
3 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
bcrypt_lib.node: invalid ELF header inside a Docker container
Error: /app/node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node: invalid ELF header
bcrypt is a compiled addon, so the file in node_modules only runs on the operating system it was installed on.
3 causes, each with a fixServers
cdk deploy fails in a GitLab job with spawnSync docker ENOENT
code: 'ENOENT'
ENOENT means the operating system found no docker program to run.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
The Next.js container starts with docker run but Compose fails with next: not found
/bin/sh: 1: next: not found
The shell cannot find the next binary.
3 causes, each with a fix