RangeError [ERR_OUT_OF_RANGE]: The value of "offset" is out of range. It must be >= 0 and <= 3. Received 4
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
for (let i = 0; i <= buf.length; i++) {
octeti.push(buf.readUInt8(i));
}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
// antet: 2 octeți tip + 2 octeți lungime
const lungime = antet.readUInt16BE(3);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
const temp = pachet.readInt16BE(4);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ă 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ă.
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;
}Semnătură: 50 4b 03 04
Indiciu
Ultima poziție validă într-un buffer de 4 octeți este 3.
Reparația
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;
}De ce merge
Un buffer de 4 octeți are pozițiile 0, 1, 2 și 3. Cu i <= antet.length, bucla mai făcea o iterație cu i = 4, iar readUInt8(4) cerea un octet care nu există, de aceea Node a spus că offset-ul trebuie să fie cel mult 3. Cu i < antet.length, bucla se oprește la ultimul octet valid și afișează toată semnătura: 50 4b sunt literele „PK”, cu care încep fișierele ZIP.
Alte forme ale mesajului
RangeError [ERR_OUT_OF_RANGE]: The value of "offset" is out of range. It must be >= 0 and <= 2. Received 4RangeError [ERR_OUT_OF_RANGE]: The value of "offset" is out of range. It must be >= 0 && <= 3. Received 4RangeError [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, saufor (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
RangeError [ERR_BUFFER_OUT_OF_BOUNDS]: Attempt to access memory outside buffer bounds Încerci să citești sau să scrii un câmp mai mare decât tot bufferul, de exemplu 4 octeți (readInt32BE) dintr-un buffer de 2. Verifică dimensiunea câmpului din format (16 sau 32 de biți?) și lungimea bufferului, de obicei rezultatul unui slice sau subarray. RangeError [ERR_OUT_OF_RANGE]: The value of "value" is out of range. It must be >= 0 and <= 255. Received 300 Numărul pe care îl scrii nu încape în tipul ales: writeUInt8 acceptă 0-255, writeInt8 -128..127, writeUInt16BE 0-65535. Alege un tip mai mare (writeUInt16BE, writeUInt32BE) și alocă bufferul cu octeții necesari, sau validează valoarea înainte. TypeError [ERR_INVALID_ARG_TYPE]: The first argument must be of type string or an instance of Buffer, ArrayBuffer, or Array or an Array-like Object. Received undefined Buffer.from() a primit undefined (sau un număr, un obiect) în loc de text sau octeți. De obicei valoarea vine dintr-o proprietate inexistentă, de exemplu req.headers.Authorization, când Node păstrează antetele cu litere mici. Verifică valoarea înainte de Buffer.from. Î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.
