Node.js app says Cannot find module only when it runs under Docker Compose
Error: Cannot find module 'express'Short answer
The image installed node_modules, but a Compose volume mounted over the app folder hides them. A bind mount of your source covers the whole folder, including node_modules. Mount an extra volume on the node_modules path, and recreate that volume after package.json changes, because an old one keeps the old packages.
Fix it fast
1Find out which cause you have
List node_modules from inside a fresh container. If the folder is empty or missing, a mount is covering what the image built.
docker compose run --rm app ls /usr/src/app/node_modules | head docker compose config | grep -A6 "volumes:"2Match what you see, then jump to its fix
- 1
The same image runs fine with docker run, but fails under Compose, and ls shows no node_modulesA bind mount of the source folder hides node_modules from the imageFix - 2
You added a dependency to package.json and rebuilt, but the new package is still not foundAn old anonymous node_modules volume still holds the previous packagesFix - 3
node_modules exists but holds old versions after a rebuild, and the volume has a name in docker volume lsA named volume on node_modules is not empty, so it hides the new image contentFix
- 1
What does the error look like?
Error: Cannot find module 'express'The same image starts fine with docker run but fails with docker compose up
Cause 1 of 3
A bind mount of the source folder hides node_modules from the image
1Check
Look for a volumes entry such as ./:/usr/src/app on the service. Docker states that when you bind mount over a directory that already has files, the existing contents are obscured by the mount.
docker compose config | grep -n "usr/src/app"
ls node_modules 2>/dev/null | head -32Fix
Add a second volume that points at node_modules only. It is mounted after the bind mount, so the packages the image installed stay visible. Replace the path with your WORKDIR.
services:
app:
build: .
volumes:
- ./:/usr/src/app
- /usr/src/app/node_modules3Verify
Recreate the container and require a package from inside it.
docker compose up -d --build
docker compose exec app node -e "require('express'); console.log('ok')"Confirmed by docs.docker.com
Cause 2 of 3
An old anonymous node_modules volume still holds the previous packages
1Check
A volume on /usr/src/app/node_modules is filled from the image only the first time. Later containers reuse it, so a rebuilt image does not refresh it. List the volumes Compose created for the project.
docker volume ls2Fix
Start with new anonymous volumes, or remove the project's volumes with down.
docker compose up --build --renew-anon-volumes
# or, to remove the project's volumes first
docker compose down --volumes3Verify
Check that the new package resolves inside the container.
docker compose exec app node -e "require('my-new-package'); console.log('ok')"Confirmed by docs.docker.com
Cause 3 of 3
A named volume on node_modules is not empty, so it hides the new image content
1Check
Docker copies image content into a volume only when the volume is empty. A volume that already has files keeps them, and the image's files at that path are obscured.
docker volume ls
docker compose config | grep -B2 -A2 node_modules2Fix
Remove the volume so it is filled again from the image on the next start.
docker compose down --volumes
docker compose up -d --build3Verify
Confirm the package list inside the container matches package.json.
docker compose exec app npm ls --depth=0Confirmed by docs.docker.com
How do I stop it coming back?
- Keep node_modules out of the build context with a .dockerignore entry, and never mount a host node_modules into the container.
- After changing package.json, rebuild with docker compose up --build and renew the node_modules volume.
- Write the node_modules path in Compose as the same path as WORKDIR in the Dockerfile, so the two cannot drift apart.
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.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Servers
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
EACCES permission denied when a container creates node_modules/.cache
The dev server exits right after start when node_modules is a Compose volume
The container user cannot write inside node_modules because the folder is owned by root.
2 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