...
Eroare Node.js · Module CommonJS: require și module.exports

Warning: Accessing non-existent property 'formatLei' of module exports inside circular dependency

Pe scurt

Două module se cer reciproc cu require (dependență circulară), iar unul citește un export al celuilalt înainte ca acesta să termine de rulat, deci primește undefined. Rupe ciclul: mută funcțiile comune într-un modul separat sau citește proprietatea abia în momentul în care o folosești.

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

Ce înseamnă

Mesajul apare când a.js cere b.js, iar b.js cere înapoi a.js (direct sau prin alte module). Ca să nu intre într-o buclă infinită, Node îi dă lui b.js obiectul module.exports al lui a.js așa cum e în acel moment: incomplet, pentru că a.js s-a oprit la linia cu require și n-a ajuns încă la exporturi.

Dacă b.js citește imediat o proprietate din acest obiect (de obicei prin destructurare: const { formatLei } = require("./a")), primește undefined. Node observă că proprietatea nu există în exporturile unui modul aflat într-un ciclu și afișează acest warning, cu numele proprietății.

Warning-ul nu oprește programul, dar de obicei urmează imediat TypeError: formatLei is not a function, când funcția e chiar apelată. Ca să afli unde se închide ciclul, rulează node --trace-warnings index.js: stiva arată lanțul de require. Ordinea în care modulele sunt încărcate prima dată decide cine primește exporturile incomplete, de aceea eroarea apare uneori doar după ce schimbi ordinea importurilor.

De ce apare: cauzele frecvente

1Două module care se cer unul pe altul

Greșit
JavaScript
// cos.js
const { formatLei } = require("./format");

// format.js
const cos = require("./cos");
Corect
JavaScript
// lei.js (fără alte require-uri)
exports.formatLei = (s) => `${s.toFixed(2)} lei`;

// cos.js și format.js
const { formatLei } = require("./lei");

Funcția de care au nevoie amândouă stă acum într-un modul care nu cere nimic înapoi, deci ciclul dispare și fiecare modul primește exporturi complete.

2Destructurare la începutul fișierului

Greșit
JavaScript
const { totalCos } = require("./cos");

function formatBon(p) {
  return totalCos(p);
}
Corect
JavaScript
const cos = require("./cos");

function formatBon(p) {
  return cos.totalCos(p);
}

Destructurarea copiază valoarea din acel moment (undefined). Păstrând obiectul și citind cos.totalCos abia la apel, găsești funcția, cu condiția ca cos.js să adauge proprietăți pe exports, nu să înlocuiască tot obiectul.

3Fișierul index (barrel) cerut înapoi din propriile module

Greșit
JavaScript
// utils/index.js
module.exports = { ...require("./bani"), ...require("./text") };

// utils/text.js
const { formatLei } = require("./index");
Corect
JavaScript
// utils/text.js
const { formatLei } = require("./bani");

Un modul din interiorul unui dosar nu trebuie să ceară index.js-ul dosarului, care îl cere la rândul lui. Cere direct fișierul de care are nevoie.

Repară tu

Repară eroarea, direct în pagină

Modulele cos.js și format.js se cer reciproc, iar programul dă Warning: Accessing non-existent property 'formatLei' of module exports inside circular dependency, urmat de TypeError. Nu poți modifica acum cele două module. Schimbă în index.js ordinea în care le încarci, ca ciclul să se închidă fără exporturi lipsă și programul să afișeze totalul și bonul.

Codul care dă eroarea
JavaScript
// Proiectul tratează orice warning ca pe o eroare (ca în CI): îl afișează și oprește cu cod 1.
process.on("warning", (w) => {
  console.error(`${w.code ? `[${w.code}] ` : ""}${w.name}: ${w.message}`);
  process.exitCode = 1;
});

const { formatBon } = require("./format");
const { afiseazaTotal } = require("./cos");

const produse = [
  { nume: "Cafea", pret: 42, cantitate: 2 },
  { nume: "Cană", pret: 35.5, cantitate: 1 },
];

try {
  console.log(afiseazaTotal(produse));
  console.log(formatBon(produse));
} catch (e) {
  console.error(`Eroare: ${e.message}`);
  process.exitCode = 1;
}
După reparație, programul afișează
Total coș: 119.50 lei
Bon fiscal: 2 produse, 119.50 lei
Indiciu

format.js nu citește nimic din cos la încărcare, dar cos.js destructurează imediat formatLei. Care dintre ele trebuie încărcat primul?

Alte forme ale mesajului

  • Warning: Accessing non-existent property 'totalCos' of module exports inside circular dependency
  • (node:4120) Warning: Accessing non-existent property 'config' of module exports inside circular dependency (Use `node --trace-warnings ...` to show where the warning was created)
  • Warning: Accessing non-existent property 'default' of module exports inside circular dependency

Cum o eviți pe viitor

  • Desenează (sau măcar gândește) dependențele: modulele de bază (formatare, configurare, constante) nu cer niciodată modulele de nivel mai înalt.
  • Pune funcțiile folosite din mai multe locuri într-un modul propriu, fără alte require-uri.
  • Nu cere index.js-ul unui dosar din fișierele aceluiași dosar.
  • Tratează warning-ul ca pe o eroare: rulează cu --trace-warnings și repară ciclul imediat.
  • Unelte ca madge --circular găsesc automat ciclurile dintr-un proiect.

Întrebări frecvente

De ce mergea până am schimbat ordinea require-urilor?

Modulul încărcat primul ajunge să ruleze complet abia la final, după ce celălalt modul l-a citit pe jumătate. Schimbând ordinea, schimbi cine primește exporturile incomplete. Ciclul exista și înainte, doar că nu se citea nimic lipsă.

Pot ignora warning-ul dacă programul pare să meargă?

Nu e recomandat. Înseamnă că un modul a citit o valoare undefined. Dacă azi nu o folosește, mâine o refactorizare mică o va face să pice cu is not a function.

Se întâmplă și cu import/export?

Ciclurile există și în modulele ES, dar acolo importurile sunt legături vii, nu copii. De obicei primești ReferenceError: Cannot access 'x' before initialization dacă folosești valoarea prea devreme.

Erori înrudite

← Toate erorile Node.js

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ță 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.