TypeError: Converting circular structure to JSON
`JSON.stringify` a dat peste un obiect care se conține pe el însuși, direct sau printr-un lanț (de exemplu un copil cu referință la părinte). JSON nu poate reprezenta cicluri. Serializează doar câmpurile de care ai nevoie, elimină referința înapoi sau folosește un replacer.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
JSON.stringify parcurge obiectul în adâncime și scrie fiecare proprietate. Dacă un obiect are o proprietate care duce, mai devreme sau mai târziu, înapoi la el, parcurgerea nu s-ar termina niciodată, așa că funcția se oprește cu Converting circular structure to JSON.
În Chrome și Node, mesajul complet arată și ciclul:
--> starting at object with constructor 'Object'
| property 'angajati' -> object with constructor 'Array'
| index 0 -> object with constructor 'Object'
--- property 'firma' closes the circleCitești de sus în jos: obiectul de start, drumul prin proprietăți și proprietatea care închide cercul (aici firma).
Cazuri tipice: structuri părinte-copil cu referință înapoi (copil.parinte = parinte), elemente DOM, obiecte de request/response din Express sau Axios, instanțe de biblioteci, sau obiecte de eroare cu context atașat. Aproape niciodată nu ai nevoie să serializezi tot obiectul: alege câmpurile utile.
De ce apare: cauzele frecvente
1Referință înapoi la părinte
const firma = { nume: "AP", angajati: [] };
const ana = { nume: "Ana", firma };
firma.angajati.push(ana);
JSON.stringify(firma);const firma = { nume: "AP", angajati: [] };
const ana = { nume: "Ana", firma };
firma.angajati.push(ana);
JSON.stringify({
nume: firma.nume,
angajati: firma.angajati.map((a) => a.nume)
});Serializezi o formă simplificată, fără referința firma din fiecare angajat.
2Replacer care omite cheia ciclică
JSON.stringify(nod);JSON.stringify(nod, (cheie, valoare) => (cheie === "parinte" ? undefined : valoare));Un replacer care returnează undefined elimină proprietatea din rezultat.
3Obiecte mari de bibliotecă
app.get("/", (req, res) => {
console.log(JSON.stringify(req));
});app.get("/", (req, res) => {
console.log(JSON.stringify({ metoda: req.method, url: req.url }));
});Obiectele de request conțin referințe interne ciclice. Extrage doar câmpurile utile.
Repară eroarea, direct în pagină
Fiecare sarcină din proiectul de mai jos are o referință înapoi la proiect, iar JSON.stringify(proiect) se oprește cu TypeError: Converting circular structure to JSON. Folosește un replacer care omite cheia proiect ca programul să afișeze JSON-ul proiectului fără referința înapoi.
const proiect = { nume: "Site nou", sarcini: [] };
proiect.sarcini.push({ titlu: "Design", proiect });
proiect.sarcini.push({ titlu: "Cod", proiect });
console.log(JSON.stringify(proiect));{"nume":"Site nou","sarcini":[{"titlu":"Design"},{"titlu":"Cod"}]}Indiciu
Al doilea argument al lui JSON.stringify poate fi o funcție (cheie, valoare) => ...; dacă returnează undefined, cheia e omisă.
Reparația
const proiect = { nume: "Site nou", sarcini: [] };
proiect.sarcini.push({ titlu: "Design", proiect });
proiect.sarcini.push({ titlu: "Cod", proiect });
console.log(JSON.stringify(proiect, (cheie, valoare) => (cheie === "proiect" ? undefined : valoare)));De ce merge
Fiecare sarcină conține proprietatea proiect, care arată înapoi spre obiectul de pornire: proiect → sarcini → sarcina → proiect, la nesfârșit. JSON nu poate reprezenta un astfel de ciclu. Replacer-ul este apelat pentru fiecare cheie; pentru proiect returnează undefined, iar JSON.stringify omite proprietatea. Restul structurii se serializează normal.
Alte forme ale mesajului
TypeError: Converting circular structure to JSON --> starting at object with constructor 'Object' --- property 'parinte' closes the circleTypeError: cyclic object valueTypeError: JSON.stringify cannot serialize cyclic structures.
Cum o eviți pe viitor
- Serializează date simple (DTO): construiește explicit obiectul care pleacă spre server sau spre fișier.
- În structurile părinte-copil, ține legătura printr-un ID (
parinteId), nu prin obiectul întreg. - Pentru afișare în consolă,
console.log(obj)arată și obiectele ciclice, fărăJSON.stringify. - Pentru copii profunde de obiecte ciclice, folosește
structuredClone, care suportă cicluri.
Întrebări frecvente
Cum găsesc ciclul?
Citește mesajul complet din Chrome sau Node: îți arată drumul prin proprietăți și cheia care închide cercul.
structuredClone merge pe obiecte ciclice?
Da, structuredClone copiază corect și structurile ciclice. Nu produce însă text, deci nu înlocuiește JSON.stringify pentru trimiterea datelor.
Erori înrudite
TypeError: Do not know how to serialize a BigInt `JSON.stringify` a găsit o valoare `BigInt` (de exemplu `123n`), pe care JSON nu știe să o reprezinte. Transform-o în text (`valoare.toString()`) sau în număr, cu un replacer, înainte de serializare. RangeError: Maximum call stack size exceeded O funcție se apelează pe ea însăși (direct sau prin altele) de prea multe ori, de obicei la nesfârșit: lipsește cazul de bază al recursivității, condiția de oprire nu e atinsă niciodată sau un getter/setter se apelează singur. Adaugă sau corectează condiția de oprire. Învață JavaScript de la zero, cu exerciții la fiecare lecție
Curs JavaScript: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.
