Node.js in Docker Compose cannot find mysql2/promise
Error: 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.
Fix it fast
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/mysql22Match what you see, then jump to its fix
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_modules2Fix
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/mysql2Confirmed by docs.docker.com
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.json2Fix
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 app3Verify
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
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Databases
mongodb-memory-server will not start under Jest or in Docker
NoSystemBinaryFoundError
When mongodb-memory-server fails to start, the real reason is hidden behind a generic message.
4 causes, each with a fixDatabases
Prisma says P1000: the database credentials are not valid
Please make sure to provide valid database credentials for the database server at `localhost`.
P1000 means the server was reached but rejected the user and password in DATABASE_URL.
3 causes, each with a fixDatabases
Prisma says it can't reach the database server, but the database is up
Please make sure your database server is running at `localhost`:`5432`.
P1001 is Prisma's catch-all for any failed connection, even a wrong password, so do not trust the label.
4 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
A container cannot resolve the name of its database container
php_network_getaddresses: getaddrinfo failed
127.0.0.11 is Docker's own DNS server for custom networks.
3 causes, each with a fixDatabases
EF Core says 'transient failure' when it cannot reach PostgreSQL in Docker
The query fails only after a delay, because the connection is retried several times
The transient failure message comes from EF Core's retry layer, which hides the underlying connection error.
3 causes, each with a fix