...
Eroare Node.js · Buffer, crypto și assert

TypeError: The encoded data was not valid for encoding utf-8

Pe scurt

Un TextDecoder creat cu { fatal: true } a primit octeți care nu sunt UTF-8 valid, de obicei un fișier salvat în altă codificare (Windows-1250, Latin-1), cum exportă Excel-ul vechi. Decodează cu codificarea reală a fișierului, de exemplu new TextDecoder("windows-1250"), sau cere fișierul în UTF-8.

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

Ce înseamnă

TextDecoder transformă octeți în text. Implicit, octeții invalizi sunt înlocuiți în tăcere cu �. Cu opțiunea { fatal: true }, decodorul aruncă în schimb TypeError cu codul ERR_ENCODING_INVALID_ENCODED_DATA, ca să nu salvezi text stricat fără să afli.

În UTF-8, literele românești ocupă doi octeți (â = C3 A2). În Windows-1250 sau ISO-8859-2, aceeași literă e un singur octet (E2). Un octet E2 urmat de o literă obișnuită nu e o secvență UTF-8 validă, deci decodorul se oprește.

Situații tipice: CSV-uri exportate din Excel sau din programe de contabilitate vechi, fișiere venite de la parteneri, loguri din aplicații Windows, cereri HTTP cu charset greșit. Dacă fără fatal vezi P�ine în loc de Pâine, e aceeași problemă, doar ascunsă.

De ce apare: cauzele frecvente

1CSV salvat în Windows-1250

Greșit
JavaScript
const text = new TextDecoder("utf-8", { fatal: true }).decode(continut);
Corect
JavaScript
const text = new TextDecoder("windows-1250").decode(continut);

Decodorul trebuie să folosească aceeași codificare în care a fost salvat fișierul.

2Detectare simplă și varianta de rezervă

Greșit
JavaScript
const text = continut.toString("utf8"); // apare P�ine, fără eroare
Corect
JavaScript
let text;
try {
  text = new TextDecoder("utf-8", { fatal: true }).decode(continut);
} catch {
  text = new TextDecoder("windows-1250").decode(continut);
}

Încerci întâi UTF-8 strict; dacă octeții nu sunt valizi, treci pe codificarea veche pe care o primești de obicei.

3Bucăți de stream decodate separat

Greșit
JavaScript
rs.on("data", (b) => text += dec.decode(b)); // o literă tăiată între bucăți
Corect
JavaScript
rs.on("data", (b) => text += dec.decode(b, { stream: true }));
rs.on("end", () => text += dec.decode());

Cu { stream: true }, decodorul păstrează octeții unei litere tăiate până vine bucata următoare.

Repară tu

Repară eroarea, direct în pagină

Fișierul cu prețuri primit de la furnizor (octeții din continut) e salvat în Windows-1250, nu în UTF-8. Decodorul UTF-8 strict aruncă The encoded data was not valid for encoding utf-8. Decodează conținutul cu codificarea lui reală, ca programul să afișeze produsele cu prețurile.

Codul care dă eroarea
JavaScript
// octeții fișierului preturi.csv, exportat dintr-un program vechi (Windows-1250)
const continut = Buffer.from([
  0x50, 0xe2, 0x69, 0x6e, 0x65, 0x3b, 0x34, 0x2e, 0x35, 0x30, 0x0a,
  0x42, 0x72, 0xe2, 0x6e, 0x7a, 0xe3, 0x3b, 0x32, 0x33, 0x2e, 0x39, 0x30,
]);

const text = new TextDecoder("utf-8", { fatal: true }).decode(continut);

for (const linie of text.split("\n")) {
  const [produs, pret] = linie.split(";");
  console.log(`${produs}: ${pret} lei`);
}
După reparație, programul afișează
Pâine: 4.50 lei
Brânză: 23.90 lei
Indiciu

new TextDecoder("windows-1250") știe să citească octeții E2 (â) și E3 (ă).

Alte forme ale mesajului

  • TypeError [ERR_ENCODING_INVALID_ENCODED_DATA]: The encoded data was not valid for encoding utf-8
  • TypeError: The encoded data was not valid for encoding utf-16le
  • TypeError: Failed to execute 'decode' on 'TextDecoder': The encoded data was not valid.
  • code: 'ERR_ENCODING_INVALID_ENCODED_DATA'

Cum o eviți pe viitor

  • Cere fișierele în UTF-8 (în Excel: „CSV UTF-8 (delimitat prin virgulă)”).
  • Folosește { fatal: true } la importuri, ca să afli imediat de o codificare greșită, în loc să salvezi � în baza de date.
  • Documentează codificarea fiecărei surse externe și decodează explicit cu ea.
  • La stream-uri, decodează cu { stream: true } sau folosește setEncoding("utf8").

Întrebări frecvente

De ce Buffer.toString() nu dă eroare?

buf.toString("utf8") nu are mod strict: înlocuiește octeții invalizi cu �. De aceea problema trece neobservată până când clienții văd texte stricate.

Ce codificare au fișierele vechi românești?

Cel mai des Windows-1250 (Windows, Excel) sau ISO-8859-2. Atenție: ambele au doar variantele cu sedilă pentru ș și ț, deci la conversie e bine să le înlocuiești cu cele cu virgulă.

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.