How to fix RangeError: Invalid typed array length (buffer size exceeds max) in Node.js

Node.jsINTERMEDIATEHIGHUpdated Dec 9, 2025· 290 views

This error occurs when attempting to create a Buffer or typed array larger than the platform maximum (typically 2GB on 32-bit systems, 4GB on 64-bit). The allocation fails because V8 cannot handle arrays larger than what a Small Integer can represent.

Quick fix

Fixes ERR_BUFFER_TOO_LARGE

const sizeInBytes = calculateBufferSize();
console.log('Attempting to allocate buffer of size:', sizeInBytes);

if (sizeInBytes > 2147483647) {
  console.error('Buffer size exceeds maximum:', sizeInBytes);
  // Handle error appropriately
}
  1. Verify the buffer size you are attempting to allocate
  2. Use streaming instead of loading entire data into memory
  3. Break large operations into smaller buffer allocations
  4. Increase Node.js heap size if needed (with caution)
node.js — error
const sizeInBytes = calculateBufferSize();
console.log('Attempting to allocate buffer of size:', sizeInBytes);
if (sizeInBytes > 2147483647) {
  console.error('Buffer size exceeds maximum:', sizeInBytes);
  // Handle error appropriately
}
RangeError: Invalid typed array length (buffer size exceeds max)

What this error means

This error is thrown by Node.js when you attempt to allocate a Buffer or typed array that exceeds the maximum size supported by your platform. The limit exists because V8, the JavaScript engine underlying Node.js, uses Small Integers (SMI) for array indexing, which are limited to 2³¹-1 (approximately 2.1 billion bytes) on 32-bit systems and around 2³² on 64-bit systems. Buffers in Node.js are stored in "external memory" outside the V8 heap, but they still inherit size constraints from V8's typed array implementation. When you try to create a buffer larger than these limits—whether directly through Buffer.alloc(), Buffer.allocUnsafe(), or indirectly through operations like reading large files—Node.js throws this RangeError to prevent undefined behavior. The error is particularly common when working with large file operations, network responses, or data processing tasks where buffer sizes are not validated before allocation.

Typical symptoms

  • Application crashes with "RangeError: Invalid typed array length" when processing large files
  • Error occurs when attempting to download or upload files larger than 2GB
  • Buffer.alloc() or Buffer.allocUnsafe() calls fail with range error
  • File read operations fail on files approaching or exceeding gigabyte sizes
  • ArrayBuffer allocation fails when posting large request bodies
  • Stream operations fail with "buffer allocation failed" messages

Common causes

  1. Attempting to allocate a buffer larger than 2³¹-1 bytes (2GB) on most platforms
  2. Reading entire large files into memory instead of streaming them in chunks
  3. Creating typed arrays with lengths exceeding platform maximum
  4. Accumulating data in a single buffer without size validation
  5. Using incorrect data types that result in unexpectedly large buffer sizes
  6. Memory calculations that produce negative or floating-point buffer lengths

How to fix "RangeError: Invalid typed array length (buffer size exceeds max)"

1Verify the buffer size you are attempting to allocate

Check your code to identify where the large buffer allocation is happening. Log the size before allocation:

javascript
const sizeInBytes = calculateBufferSize();
console.log('Attempting to allocate buffer of size:', sizeInBytes);

if (sizeInBytes > 2147483647) {
  console.error('Buffer size exceeds maximum:', sizeInBytes);
  // Handle error appropriately
}

The maximum safe size is 2,147,483,647 bytes (2³¹-1), approximately 2GB.

2Use streaming instead of loading entire data into memory

For large files or data, process them in chunks using streams instead of allocating one massive buffer:

javascript
import fs from 'fs';
import { pipeline } from 'stream/promises';

// Instead of fs.readFileSync() or fs.readFile()
const readStream = fs.createReadStream('large-file.dat', {
  highWaterMark: 64 * 1024, // 64KB chunks
});

const writeStream = fs.createWriteStream('output.dat');

// Process in chunks
await pipeline(
  readStream,
  // Transform stream if needed
  async function* (source) {
    for await (const chunk of source) {
      // Process each chunk
      yield processChunk(chunk);
    }
  },
  writeStream
);

This approach processes data incrementally without requiring large buffer allocations.

3Break large operations into smaller buffer allocations

If you must work with large datasets, split them into manageable chunks:

javascript
const CHUNK_SIZE = 100 * 1024 * 1024; // 100MB chunks
const totalSize = fileStats.size;
const numChunks = Math.ceil(totalSize / CHUNK_SIZE);

for (let i = 0; i < numChunks; i++) {
  const start = i * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, totalSize);
  const chunkSize = end - start;

  // Allocate smaller buffer for each chunk
  const buffer = Buffer.alloc(chunkSize);

  // Read chunk from file
  await fs.promises.read(fd, buffer, 0, chunkSize, start);

  // Process buffer
  await processBuffer(buffer);
}
4Increase Node.js heap size if needed (with caution)

If your application legitimately needs more memory for non-Buffer objects, increase the V8 heap size:

bash
# Increase old space to 4GB
node --max-old-space-size=4096 your-script.js

# Or set in package.json scripts
{
  "scripts": {
    "start": "node --max-old-space-size=4096 index.js"
  }
}

Note: This does NOT increase Buffer allocation limits, as Buffers use external memory. This only helps if you're hitting heap limits with regular JavaScript objects.

5Validate input sizes before allocation

Add guards to prevent allocation attempts that will fail:

javascript
function safeBufferAlloc(size) {
  const MAX_BUFFER_SIZE = 2147483647; // 2^31 - 1

  if (size > MAX_BUFFER_SIZE) {
    throw new Error(
      `Requested buffer size (${size}) exceeds maximum (${MAX_BUFFER_SIZE})`
    );
  }

  if (size < 0 || !Number.isInteger(size)) {
    throw new Error('Buffer size must be a positive integer');
  }

  return Buffer.alloc(size);
}

// Use in your code
try {
  const buffer = safeBufferAlloc(requestedSize);
} catch (error) {
  console.error('Cannot allocate buffer:', error.message);
  // Handle gracefully - use streaming, split data, or reject request
}

Advanced notes

Platform-Specific Limits: The exact maximum buffer size varies by platform. On 32-bit systems, the limit is strictly 2³¹-1 bytes (2,147,483,647). On 64-bit systems, ArrayBuffer can theoretically support up to 2³³ (8GB) in modern browsers like Firefox 89+, but Node.js typically enforces the 2GB limit for consistency and safety.

External Memory vs Heap: Buffers in Node.js use "external memory" allocated outside the V8 heap. This means increasing --max-old-space-size won't allow larger buffers, but it may help if you're storing many references to buffers or other heap objects. V8 doesn't automatically trigger garbage collection based on external memory pressure, which can lead to memory bloat if not managed carefully.

libuv I/O Constraints: Even with streaming, be aware that libuv (Node's I/O layer) limits individual read operations to 2GB. For files larger than this, you must explicitly handle multiple read operations with proper offset tracking.

Performance Considerations: Large buffer allocations, even when within limits, can cause performance issues. Buffer.allocUnsafe() is faster than Buffer.alloc() because it doesn't zero-fill memory, but use it only when you'll immediately overwrite all bytes to avoid security vulnerabilities from exposing old memory contents.

Alternative Architectures: For truly massive datasets (>2GB), consider architectural alternatives like memory-mapped files (using mmap through native addons), database streaming, or splitting data into separate files that can be processed independently.

Frequently asked questions

What does "ERR_BUFFER_TOO_LARGE" mean?
js when you attempt to allocate a Buffer or typed array that exceeds the maximum size supported by your platform. 1 billion bytes) on 32-bit systems and around 2³² on 64-bit systems. js are stored in "external memory" outside the V8 heap, but they still inherit size constraints from V8's typed array implementation.
How do I fix "ERR_BUFFER_TOO_LARGE"?
This error occurs when attempting to create a Buffer or typed array larger than the platform maximum (typically 2GB on 32-bit systems, 4GB on 64-bit). The allocation fails because V8 cannot handle arrays larger than what a Small Integer can represent.
What causes "ERR_BUFFER_TOO_LARGE"?
Attempting to allocate a buffer larger than 2³¹-1 bytes (2GB) on most platforms Reading entire large files into memory instead of streaming them in chunks Creating typed arrays with lengths exceeding platform maximum
Is the "ERR_BUFFER_TOO_LARGE" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading