Maaz Zindani

Loading the index…

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

Node.js app says Cannot find module only when it runs under Docker Compose

ErrorError: 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.

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

Fix it fast

  1. 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:"
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2You 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. 3node_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

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 -3

2Fix

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_modules

3Verify

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

Did this fix it?

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 ls

2Fix

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 --volumes

3Verify

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

Did this fix it?

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_modules

2Fix

Remove the volume so it is filled again from the image on the next start.

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

3Verify

Confirm the package list inside the container matches package.json.

docker compose exec app npm ls --depth=0

Confirmed by docs.docker.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.