denoland/deno · error · NodeRangeError

ERR_FS_FILE_TOO_LARGE

ERR_FS_FILE_TOO_LARGE

Error message

File size (${x}) is greater than 2 GB

What it means

Thrown by readFileFromFd when fstat reports a regular file whose size exceeds kIoMaxLength (2^31 - 1 bytes, about 2 GiB). fs.readFile buffers the whole file in one Uint8Array, and the polyfill refuses sizes above this hard limit instead of exhausting memory, mirroring Node's ERR_FS_FILE_TOO_LARGE.

Source

Thrown at ext/node/polyfills/fs.ts:733

    TypedArrayPrototypeSet(contents, buf, n);
    n += TypedArrayPrototypeGetByteLength(buf);
  }

  return contents;
}

async function readFileFromFd(fd: number, options?: FileOptions) {
  const signal = options?.signal;
  readFileCheckAborted(signal);

  const statFields = op_node_fs_fstat_sync(fd);
  readFileCheckAborted(signal);

  const isFile = statFields.isFile;
  const size = isFile ? statFields.size : 0;

  if (size > kIoMaxLength) {
    throw new ERR_FS_FILE_TOO_LARGE(size);
  }

  if (isFile && size > 0) {
    // Known size: read into a single buffer with an advancing offset.
    // Mirrors Node's readFileHandle which avoids the subarray-aliasing trap
    // by writing successive reads into different regions of one buffer.
    const buffer = new Uint8Array(size);
    let totalRead = 0;
    while (totalRead < size) {
      readFileCheckAborted(signal);
      const slice = TypedArrayPrototypeSubarray(buffer, totalRead);
      // Use the deferred op so we yield to the event loop between reads,
      // allowing abort signals scheduled via lazyProcess().default.nextTick to fire.
      const nread = await op_node_fs_read_deferred(fd, slice, -1n);
      if (nread === 0) break;
      totalRead += nread;
    }
    readFileCheckAborted(signal);

View on GitHub (pinned to 89f33cbef2)

Solutions

1. Switch to streaming with fs.createReadStream(path) and process chunks incrementally
2. Use fs.promises.open + a manual read loop over fixed-size buffers
3. For line-oriented data, read via readline.createInterface over a read stream
4. Check fs.stat(path).size against 2 ** 31 - 1 before calling readFile to fail fast

Example fix

// before
const data = await fs.promises.readFile(bigFile); // ERR_FS_FILE_TOO_LARGE

// after
for await (const chunk of fs.createReadStream(bigFile)) {
  handleChunk(chunk);
}

const MAX = 2 ** 31 - 1;
const { size } = await fs.promises.stat(path);
if (size > MAX) {
  // stream instead of readFile
}

When it happens

Trigger: fs.readFile / fs.promises.readFile on a regular file larger than 2147483647 bytes (ISO images, database dumps, large logs, ML datasets).

Common situations: Scripts that worked on small test fixtures but run against production-sized archives; log ingestion tools; build steps reading bundled artifacts that grew past 2 GiB.

Related errors

• ERR_FS_CP_UNKNOWN
• ERR_INVALID_ARG_TYPE
• ABORT_ERR
• No callback function supplied
• invalid ${name}, must not be infinity or NaN

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/04303dc59877b639. Report an issue: GitHub.