This error occurs when you attempt to read from or write to a Buffer at an offset that is either negative or exceeds the buffer's bounds. Common when using Buffer methods like readUInt8(), write(), slice(), or copy() with invalid offset parameters.
Node.js Buffers have fixed sizes, and operations like reading or writing must stay within those boundaries. When you specify an offset parameter that falls outside the valid range (0 to buffer.length - 1, adjusted for the data type being read), Node.js throws an ERR_OUT_OF_RANGE error to prevent undefined behavior and potential memory corruption. This is a safety mechanism to catch programming errors early.
Verify that your offset is non-negative. Negative offsets are not allowed in Node.js buffer operations.
// BAD: negative offset
const buf = Buffer.alloc(10);
buf.readUInt8(-1); // RangeError!
// GOOD: non-negative offset
buf.readUInt8(0);Ensure the offset doesn't exceed the buffer length. For operations that read N bytes, the offset must be <= buffer.length - N.
const buf = Buffer.from([1, 2, 3, 4, 5]);
// BAD: offset 5 is out of bounds for readUInt8
buf.readUInt8(5); // RangeError!
// GOOD: offset 4 is the last valid position
buf.readUInt8(4); // OKDifferent buffer read/write methods require different amounts of space. Reading a 32-bit integer (readUInt32LE) requires 4 bytes at the offset.
const buf = Buffer.alloc(6);
// BAD: reading 4 bytes starting at offset 3 (only 3 bytes available)
buf.readUInt32LE(3); // RangeError!
// GOOD: reading 4 bytes with enough space
buf.readUInt32LE(2); // OK (bytes 2-5)Implement validation logic to ensure offsets and lengths are safe before performing buffer operations.
function safeReadUInt8(buf, offset) {
if (offset < 0 || offset >= buf.length) {
throw new Error(`Invalid offset ${offset} for buffer of length ${buf.length}`);
}
return buf.readUInt8(offset);
}
const buf = Buffer.from([10, 20, 30]);
const value = safeReadUInt8(buf, 1); // OKIf your offset comes from calculations, user input, or external data, trace through the logic and add defensive checks.
const buf = Buffer.from(data);
const offset = parseInt(userInput); // Could be anything
// GOOD: validate before use
if (offset < 0 || offset >= buf.length) {
console.error('Invalid offset provided');
return;
}
const value = buf.readUInt8(offset);Instead of calculating offsets manually, consider using slice() or subarray() which handles bounds checking automatically.
const buf = Buffer.from([1, 2, 3, 4, 5]);
// GOOD: slice() safely handles offsets
const subset = buf.slice(2, 4); // Safe, returns bytes at indices 2-3
// Or use subarray() for zero-copy approach
const view = buf.subarray(2, 4); // Also safeWhen working with fixed-size integer reads (readUInt32LE, readBigInt64BE, etc.), Node.js requires that offset + byteSize <= buffer.length. For readUInt32LE on a 10-byte buffer, valid offsets are 0-6 (not 0-9). If you're unsure about data type sizes, reference the Node.js documentation: UInt8/Int8 need 1 byte, UInt16/Int16 need 2, UInt32/Int32 need 4, BigInt64/BigUInt64 need 8. In production code dealing with binary protocols or file parsing, consider using a well-tested parser library instead of manual offset calculations, as they handle edge cases and provide better error messages.
Error: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: EACCES: permission denied, open '/root/file.txt'
EACCES: permission denied
Error: Invalid encoding specified (stream encoding not supported)
How to fix Invalid encoding error in Node.js readable streams
Error: EINVAL: invalid argument, open
EINVAL: invalid argument, open
TypeError: readableLength must be a positive integer (stream config)
TypeError: readableLength must be a positive integer in Node.js streams