Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Node.js in Docker Compose cannot find mysql2/promise

ErrorError: Cannot find module 'mysql2/promise'

Short answer

mysql2/promise is a path inside the mysql2 package. If Node.js cannot find it in a container, either mysql2 was never installed in the image, or a bind mount of your project folder is hiding the node_modules the image built. Check inside the running container first.

  • Applies to Docker Compose v2, Node.js 22, mysql2 3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look inside the running container, not on your host. If the folder is missing there, the cause is in how the image or the volumes are set up.

    docker compose exec app ls node_modules/mysql2
  2. 2Match what you see, then jump to its fix

    1. 1The compose file mounts your project folder onto the app path, for example ./:/appA bind mount hides node_modules that the image installedFix
    2. 2The folder node_modules/mysql2 is missing even without any bind mountmysql2 is not in package.json, so the image never installed itFix

What does the error look like?

  • Error: Cannot find module 'mysql2/promise'
  • The app works on the host but fails after docker compose up

Cause 1 of 2

A bind mount hides node_modules that the image installed

1Check

Docker documents that a bind mount over a directory with files in the image hides those files while the mount is in place. If the host folder has no node_modules, the container sees none.

grep -n -A4 "volumes" docker-compose.yml
docker compose exec app ls node_modules

2Fix

Keep your code mount, and add a named volume on node_modules so the dependencies from the image stay visible. Docker copies the image's files into a new named volume when it is created.

services:
  app:
    build: .
    volumes:
      - ./:/app
      - app_node_modules:/app/node_modules
volumes:
  app_node_modules:

3Verify

The folder is now present inside the container.

docker compose up -d --build
docker compose exec app ls node_modules/mysql2

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 2

mysql2 is not in package.json, so the image never installed it

1Check

A package installed by hand on your machine but never saved is not in the image either. Look for mysql2 in the dependencies.

grep -n mysql2 package.json

2Fix

Install and save the package, so package.json and the lock file list it. The Dockerfile's install step then puts it into the image.

npm install --save mysql2
docker compose build app

3Verify

Node.js loads the promise API inside the container.

docker compose run --rm app node -e "require('mysql2/promise'); console.log('ok')"

Confirmed by sidorares.github.io

Did this fix it?

How do I stop it coming back?

  • Declare every dependency with npm install --save, so builds do not depend on your machine.
  • When you mount source code, give node_modules its own volume.
  • Use npm ci in the Dockerfile so the image matches the lock file, and fails when package.json and the lock file disagree.

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.