Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: node:fs/promise
Ai cerut cu prefixul node: un modul de bază care nu există, aproape mereu din cauza unei greșeli de scriere: node:fs/promise în loc de node:fs/promises, node:paths în loc de node:path. Corectează numele; lista exactă e în require("module").builtinModules.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Prefixul node: îi spune lui Node că vrei un modul de bază (node:fs, node:path, node:crypto), nu un pachet din node_modules sau un fișier al tău. Pentru că știe sigur unde să caute, Node nu mai încearcă alte variante: dacă numele de după node: nu e în lista modulelor de bază, primești imediat ERR_UNKNOWN_BUILTIN_MODULE.
Cauza e aproape întotdeauna o literă în plus sau în minus: node:fs/promise (corect node:fs/promises), node:paths (corect node:path), node:event (corect node:events), node:http2s. Mai rar, codul e scris pentru o versiune mai nouă de Node decât cea instalată, iar modulul (de exemplu node:sqlite) încă nu există la tine.
Fără prefix, aceeași greșeală dă Cannot find module 'fs/promise', pentru că Node caută apoi și în node_modules.
De ce apare: cauzele frecvente
1Greșeală de scriere în numele modulului
const fs = require("node:fs/promise");const fs = require("node:fs/promises");Modulul cu promisiuni se numește fs/promises, la plural.
2Nume ghicit în loc de numele real
import { EventEmitter } from "node:event";
import path from "node:paths";import { EventEmitter } from "node:events";
import path from "node:path";Numele modulelor de bază sunt fixe (events, path, child_process, readline). Când nu ești sigur, verifică în require("module").builtinModules.
3Modul care nu există în versiunea ta de Node
// Node 20
const { DatabaseSync } = require("node:sqlite");// verifică versiunea
console.log(process.version);
// actualizează Node sau folosește un pachet npmModulele noi apar doar în versiunile noi. Codul copiat din documentația celei mai noi versiuni poate cere un modul pe care Node-ul tău nu îl are.
Repară eroarea, direct în pagină
Programul citește două fișiere de note cu API-ul de promisiuni al modulului fs, dar numele modulului e scris greșit și Node se oprește cu Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: node:fs/promise. Corectează numele modulului, ca programul să afișeze câte note are fiecare fișier și media lor.
const fs = require("node:fs/promise");
async function main() {
for (const fisier of ["note-mate.txt", "note-info.txt"]) {
const note = (await fs.readFile(fisier, "utf8")).trim().split("\n").map(Number);
const media = note.reduce((s, n) => s + n, 0) / note.length;
console.log(`${fisier}: ${note.length} note, media ${media.toFixed(2)}`);
}
}
main();note-mate.txt: 3 note, media 8.67 note-info.txt: 4 note, media 9.25
Indiciu
Modulul cu promisiuni pentru fișiere se scrie la plural.
Reparația
const fs = require("node:fs/promises");
async function main() {
for (const fisier of ["note-mate.txt", "note-info.txt"]) {
const note = (await fs.readFile(fisier, "utf8")).trim().split("\n").map(Number);
const media = note.reduce((s, n) => s + n, 0) / note.length;
console.log(`${fisier}: ${note.length} note, media ${media.toFixed(2)}`);
}
}
main();De ce merge
Cu prefixul node: Node caută numele doar în lista modulelor de bază, iar fs/promise nu există acolo, așa că programul se oprește înainte de prima linie din main. Modulul corect este node:fs/promises: el exportă aceleași funcții ca fs, dar fiecare întoarce o promisiune, de aceea poți scrie await fs.readFile(...).
Alte forme ale mesajului
Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: node:pathsError [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: node:eventError: Cannot find module 'node:fs/promise'Error: Cannot find module 'fs/promise'
Cum o eviți pe viitor
- Lasă editorul să completeze importurile: VS Code îți propune numele exacte ale modulelor de bază.
- Ține minte pluralele:
fs/promises,timers/promises,readline/promises,events. - Când copiezi cod de pe internet, verifică ce versiune de Node cere și compar-o cu
node -v. - Folosește prefixul
node:pentru modulele de bază: greșelile apar imediat și nu se confundă cu pachete dinnode_modules.
Întrebări frecvente
Trebuie să pun prefixul node: peste tot?
Nu e obligatoriu (require("fs") merge la fel), dar e recomandat: se vede imediat că e un modul de bază și nimeni nu îl poate înlocui cu un pachet cu același nume.
Cum văd lista modulelor de bază?
Rulează node -p "require('module').builtinModules". Lista diferă puțin de la o versiune de Node la alta.
Erori înrudite
Error: Cannot find module 'lodash' Pachetul cerut nu este instalat în node_modules: ai uitat npm install, l-ai instalat în alt dosar sau numele e scris greșit. Rulează npm install lodash (sau npm install dacă e deja în package.json) în dosarul proiectului, ori folosește o funcție inclusă în Node. TypeError: fs.readFileSync is not a function Ai importat varianta cu promisiuni a modulului (require("fs/promises") sau fs.promises), care are doar funcții asincrone, fără Sync. Folosește await fs.readFile(...) din fs/promises, sau importă modulul obișnuit "fs" dacă vrei readFileSync. Error: Cannot find module './calcul' Node nu găsește fișierul pe care îl ceri cu require: calea e scrisă greșit, fișierul are alt nume sau e în alt dosar. Verifică numele exact al fișierului și calea relativă față de fișierul care face require, de exemplu require("./calcule") sau require("./lib/calcule"). Învață Node.js de la zero, cu exerciții la fiecare lecție
Curs Node.js: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.
