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

RangeError [ERR_OUT_OF_RANGE]: The value of "offset" is out of range. It must be >= 0 and <= 3. Received 4

Pe scurt

Citești sau scrii într-un Buffer la o poziție (offset) care depășește lungimea lui. Mesajul îți dă intervalul permis și valoarea primită. De obicei e o buclă cu i <= buf.length în loc de i < buf.length, sau un câmp citit dintr-un pachet mai scurt decât crezi.

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

Ce înseamnă

Metodele de citire și scriere ale lui Buffer (readUInt8, readUInt16BE, readInt32LE, writeUInt8, writeDoubleBE și celelalte) primesc poziția de la care încep: offset-ul. Node verifică dacă valoarea încape: pentru un câmp de n octeți, offset-ul trebuie să fie între 0 și buf.length - n.

Mesajul spune exact asta: It must be >= 0 and <= 3 înseamnă că ultima poziție validă e 3, iar Received 4 e poziția cerută. Pentru un buffer de 4 octeți, readUInt8(4) e deja în afară, iar readUInt16BE(3) la fel, pentru că ar avea nevoie de octeții 3 și 4.

Cauzele tipice sunt o buclă care merge cu un pas prea departe, un offset calculat greșit (suma lungimilor câmpurilor anterioare) sau un pachet primit prin rețea mai scurt decât formatul așteptat. Dacă bufferul e mai scurt decât câmpul însuși (citești 4 octeți dintr-un buffer de 2), primești în schimb ERR_BUFFER_OUT_OF_BOUNDS.

De ce apare: cauzele frecvente

1Bucla merge până la length inclusiv

Greșit
JavaScript
for (let i = 0; i <= buf.length; i++) {
  octeti.push(buf.readUInt8(i));
}
Corect
JavaScript
for (let i = 0; i < buf.length; i++) {
  octeti.push(buf.readUInt8(i));
}

Pozițiile valide sunt de la 0 la length - 1. Cu <=, ultima iterație cere poziția length, care nu există.

2Offset calculat greșit pentru un câmp de mai mulți octeți

Greșit
JavaScript
// antet: 2 octeți tip + 2 octeți lungime
const lungime = antet.readUInt16BE(3);
Corect
JavaScript
const lungime = antet.readUInt16BE(2);

Al doilea câmp începe după primii 2 octeți, deci la poziția 2. De la poziția 3, un câmp de 2 octeți ar ieși din buffer.

3Pachet mai scurt decât formatul

Greșit
JavaScript
const temp = pachet.readInt16BE(4);
Corect
JavaScript
if (pachet.length < 6) throw new Error(`Pachet incomplet: ${pachet.length} octeți`);
const temp = pachet.readInt16BE(4);

Datele venite din afară pot fi trunchiate. Verifică lungimea înainte și dă un mesaj care explică problema.

Repară tu

Repară eroarea, direct în pagină

Programul afișează în hexazecimal primii 4 octeți ai unui fișier (semnătura unei arhive ZIP), dar dă RangeError [ERR_OUT_OF_RANGE]: The value of "offset" is out of range. It must be >= 0 and <= 3. Received 4. Repară bucla, ca programul să afișeze semnătura completă.

Codul care dă eroarea
JavaScript
const antet = Buffer.from([0x50, 0x4b, 0x03, 0x04]);

const octeti = [];
try {
  for (let i = 0; i <= antet.length; i++) {
    octeti.push(antet.readUInt8(i).toString(16).padStart(2, "0"));
  }
  console.log(`Semnătură: ${octeti.join(" ")}`);
} catch (err) {
  console.error(err.message);
  process.exitCode = 1;
}
După reparație, programul afișează
Semnătură: 50 4b 03 04
Indiciu

Ultima poziție validă într-un buffer de 4 octeți este 3.

Alte forme ale mesajului

  • RangeError [ERR_OUT_OF_RANGE]: The value of "offset" is out of range. It must be >= 0 and <= 2. Received 4
  • RangeError [ERR_OUT_OF_RANGE]: The value of "offset" is out of range. It must be >= 0 && <= 3. Received 4
  • RangeError [ERR_OUT_OF_RANGE]: The value of "offset" is out of range. It must be an integer. Received 1.5

Cum o eviți pe viitor

  • În bucle peste un buffer folosește i < buf.length, sau for (const octet of buf) când nu ai nevoie de poziție.
  • Descrie formatul binar într-un singur loc (pozițiile și lungimile câmpurilor) și calculează offset-urile din el.
  • Verifică buf.length înainte să citești date venite din rețea sau din fișiere.

Întrebări frecvente

De ce Uint8Array dă undefined, iar Buffer aruncă eroare?

Indexarea simplă (buf[10]) dă undefined și la Buffer. Metodele readUInt8 și celelalte verifică însă poziția și aruncă eroare, ca să nu lucrezi în tăcere cu date lipsă.

Ce înseamnă "It must be an integer"?

Ai dat un offset cu zecimale, de obicei rezultatul unei împărțiri (length / 2). Rotunjește-l cu Math.floor sau verifică formula.

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.