...
Eroare Docker · Containere care se opresc imediat

Error: Cannot find module 'express'

Pe scurt

Node nu găsește pachetul express în /app/node_modules, deci aplicația se oprește la pornire. Ori lipsește RUN npm install din Dockerfile, ori ai montat codul de pe calculator peste /app (-v ~/api:/app) și ai ascuns node_modules din imagine. Instalează pachetele în imagine sau într-un volum separat pentru /app/node_modules.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

require("express") caută pachetul în node_modules, începând din folderul fișierului. Dacă nu-l găsește, Node aruncă Cannot find module 'express' cu code: 'MODULE_NOT_FOUND', iar Require stack arată fișierul care l-a cerut (/app/server.js).

În Docker, două cauze domină:

  • npm install lipsă în Dockerfile, deci imaginea are codul, dar nu și dependențele;
  • bind mount peste /app: imaginea are node_modules, dar -v ~/api:/app pune folderul de pe calculator (fără node_modules, sau cu unul instalat pe macOS/Windows) peste tot /app, inclusiv peste pachete.

Diferența față de Cannot find module '/app/server.js': acolo lipsește chiar fișierul aplicației; aici lipsește un pachet npm.

De ce apare: cauzele frecvente

1Bind mount care ascunde node_modules

Greșit
BASH
docker run -d -p 3000:3000 -v ~/api:/app api:1.0
Corect
BASH
docker run --rm -v ~/api:/app -v api-modules:/app/node_modules -w /app node:20-alpine npm install
docker run -d -p 3000:3000 -v ~/api:/app -v api-modules:/app/node_modules api:1.0

Volumul separat ține pachetele instalate pentru Linux, iar bind mount-ul nu le mai acoperă.

2Dockerfile fără npm install

Greșit
BASH
FROM node:20-alpine
WORKDIR /app
COPY . .
CMD ["node", "server.js"]
Corect
BASH
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]

Pachetele din package.json se instalează în imagine la build.

3Pachetul lipsește din package.json

Greșit
BASH
npm install express   # doar pe calculator, fără să salvezi package.json
Corect
BASH
npm install express --save
# apoi docker build din nou

Imaginea instalează doar ce scrie în package.json și package-lock.json.

Repară tu

Repară eroarea, direct în pagină

În ~/api, imaginea api:1.0 e construită corect (cu npm install), dar ai pornit-o cu codul montat, -v ~/api:/app, ca să vezi modificările fără rebuild. Containerul api cade cu Cannot find module 'express'. Instalează pachetele în volumul api-modules și pornește din nou api pe portul 3000, cu codul montat în /app și volumul în /app/node_modules.

Indiciu

Rulează npm install într-un container temporar care montează codul și volumul api-modules, apoi pornește api cu ambele montări.

Alte forme ale mesajului

  • Error: Cannot find module 'dotenv'
  • node:internal/modules/cjs/loader:1228 throw err; ^ Error: Cannot find module 'express' Require stack: - /app/server.js
  • Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from /app/server.js

Cum o eviți pe viitor

Instalează mereu dependențele în Dockerfile (COPY package*.json ./ + RUN npm ci sau npm install) și pune node_modules în .dockerignore. În dezvoltare, când montezi codul, dă-i lui /app/node_modules un volum separat. Nu copia în container un node_modules instalat pe macOS sau Windows: pachetele native nu merg pe Linux.

Întrebări frecvente

Imaginea merge fără -v, dar cu -v ~/api:/app nu. De ce?

Bind mount-ul înlocuiește tot conținutul lui /app din imagine cu folderul de pe calculator. Dacă acolo nu există node_modules, pachetele instalate la build devin invizibile.

De ce să nu instalez pachetele pe calculator și să le montez?

Pachetele cu cod nativ (de exemplu bcrypt, sharp) sunt compilate pentru sistemul pe care le instalezi. Cele de pe macOS sau Windows nu pornesc în containerul Linux.

Erori înrudite

← Toate erorile Docker

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață Docker de la zero, cu exerciții la fiecare lecție

Curs Docker: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.