...
Eroare JavaScript · JSON: parse și stringify

TypeError: Do not know how to serialize a BigInt

Pe scurt

`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.

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

Ce înseamnă

BigInt este tipul JavaScript pentru numere întregi foarte mari, scrise cu n la final (9007199254740993n) sau create cu BigInt(...). Standardul JSON nu are o reprezentare pentru ele, iar JSON.stringify refuză să ghicească: dacă le-ar transforma în numere obișnuite, ar pierde precizie. De aceea aruncă Do not know how to serialize a BigInt.

Eroarea apare când ai BigInt-uri în datele pe care le trimiți la un server, le salvezi sau le afișezi cu JSON.stringify: ID-uri mari din baze de date, valori din blockchain (wei, token-uri), rezultate de calcule cu BigInt sau date venite de la biblioteci (unele drivere de baze de date întorc coloanele BIGINT ca BigInt).

Soluția uzuală este să le serializezi ca text, păstrând toate cifrele, iar cel care citește datele le transformă înapoi cu BigInt(text).

De ce apare: cauzele frecvente

1Obiect cu un câmp BigInt

Greșit
JavaScript
const plata = { id: 9007199254740993n, suma: 150 };
JSON.stringify(plata);
Corect
JavaScript
const plata = { id: 9007199254740993n, suma: 150 };
JSON.stringify(plata, (k, v) => (typeof v === "bigint" ? v.toString() : v));

Replacer-ul transformă orice BigInt în text, fără să piardă cifre.

2Conversie în număr când valoarea e mică

Greșit
JavaScript
const stoc = { bucati: 42n };
JSON.stringify(stoc);
Corect
JavaScript
const stoc = { bucati: Number(42n) };
JSON.stringify(stoc);

Dacă valoarea încape sigur în Number.MAX_SAFE_INTEGER, poți folosi un număr obișnuit.

3toJSON pe prototip, pentru tot proiectul

Greșit
JavaScript
JSON.stringify({ total: 10n });
Corect
JavaScript
BigInt.prototype.toJSON = function () {
  return this.toString();
};
JSON.stringify({ total: 10n });

Funcționează, dar modifică un obiect global; preferă un replacer local când poți.

Repară tu

Repară eroarea, direct în pagină

Tranzacția de mai jos are un ID foarte mare, păstrat ca BigInt, iar JSON.stringify se oprește cu TypeError: Do not know how to serialize a BigInt. Adaugă un replacer care transformă BigInt-urile în text, ca programul să afișeze JSON-ul tranzacției cu ID-ul complet.

Codul care dă eroarea
JavaScript
const tranzactie = { id: 9007199254740993n, suma: 250, moneda: "RON" };

console.log(JSON.stringify(tranzactie));
După reparație, programul afișează
{"id":"9007199254740993","suma":250,"moneda":"RON"}
Indiciu

typeof valoare === "bigint" îți spune dacă o valoare e BigInt.

Alte forme ale mesajului

  • TypeError: BigInt value can't be serialized in JSON
  • TypeError: JSON.stringify cannot serialize BigInt.

Cum o eviți pe viitor

  • Folosește BigInt doar unde chiar ai nevoie de numere întregi mai mari decât Number.MAX_SAFE_INTEGER (9007199254740991).
  • Stabilește o regulă pentru date: BigInt-urile circulă în JSON ca text.
  • Folosește un replacer comun la toate apelurile JSON.stringify din proiect.
  • La citire, transformă textele înapoi cu BigInt(text).

Întrebări frecvente

De ce nu le transformă automat în numere?

Pentru că s-ar putea pierde precizie: numerele JavaScript pot reprezenta exact doar întregi până la 2⁵³ − 1. Un ID mare ar deveni alt număr, în tăcere.

Cum citesc înapoi valoarea?

Cu un reviver la JSON.parse sau direct: BigInt(obiect.id) transformă textul înapoi în BigInt.

Erori înrudite

← Toate erorile JavaScript

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