{"record":{"id":"04303dc59877b639","repo":"denoland/deno","slug":"err-fs-file-too-large","errorCode":"ERR_FS_FILE_TOO_LARGE","errorMessage":"File size (${x}) is greater than 2 GB","messagePattern":"File size \\((.+?)\\) is greater than 2 GB","errorType":"exception","errorClass":"NodeRangeError","httpStatus":null,"severity":"error","filePath":"ext/node/polyfills/fs.ts","lineNumber":733,"sourceCode":"    TypedArrayPrototypeSet(contents, buf, n);\n    n += TypedArrayPrototypeGetByteLength(buf);\n  }\n\n  return contents;\n}\n\nasync function readFileFromFd(fd: number, options?: FileOptions) {\n  const signal = options?.signal;\n  readFileCheckAborted(signal);\n\n  const statFields = op_node_fs_fstat_sync(fd);\n  readFileCheckAborted(signal);\n\n  const isFile = statFields.isFile;\n  const size = isFile ? statFields.size : 0;\n\n  if (size > kIoMaxLength) {\n    throw new ERR_FS_FILE_TOO_LARGE(size);\n  }\n\n  if (isFile && size > 0) {\n    // Known size: read into a single buffer with an advancing offset.\n    // Mirrors Node's readFileHandle which avoids the subarray-aliasing trap\n    // by writing successive reads into different regions of one buffer.\n    const buffer = new Uint8Array(size);\n    let totalRead = 0;\n    while (totalRead < size) {\n      readFileCheckAborted(signal);\n      const slice = TypedArrayPrototypeSubarray(buffer, totalRead);\n      // Use the deferred op so we yield to the event loop between reads,\n      // allowing abort signals scheduled via lazyProcess().default.nextTick to fire.\n      const nread = await op_node_fs_read_deferred(fd, slice, -1n);\n      if (nread === 0) break;\n      totalRead += nread;\n    }\n    readFileCheckAborted(signal);","sourceCodeStart":715,"sourceCodeEnd":751,"githubUrl":"https://github.com/denoland/deno/blob/89f33cbef296a2b287f323d42de54c871fa69c77/ext/node/polyfills/fs.ts#L715-L751","documentation":"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.","triggerScenarios":"fs.readFile / fs.promises.readFile on a regular file larger than 2147483647 bytes (ISO images, database dumps, large logs, ML datasets).","commonSituations":"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.","solutions":["Switch to streaming with fs.createReadStream(path) and process chunks incrementally","Use fs.promises.open + a manual read loop over fixed-size buffers","For line-oriented data, read via readline.createInterface over a read stream","Check fs.stat(path).size against 2 ** 31 - 1 before calling readFile to fail fast"],"exampleFix":"// before\nconst data = await fs.promises.readFile(bigFile); // ERR_FS_FILE_TOO_LARGE\n\n// after\nfor await (const chunk of fs.createReadStream(bigFile)) {\n  handleChunk(chunk);\n}","handlingStrategy":"validation","validationCode":"const MAX = 2 ** 31 - 1;\nconst { size } = await fs.promises.stat(path);\nif (size > MAX) {\n  // stream instead of readFile\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Route files above ~2 GiB through fs.createReadStream by design, not by exception","Add a size gate (stat + constant check) in upload/import pipelines before buffer APIs","Remember readFile also has to fit the file in memory even below the limit — budget accordingly"],"tags":["node-compat","filesystem","file-size","streaming"],"backgroundTag":null,"analyzedSha":"89f33cbef296a2b287f323d42de54c871fa69c77","analyzedAt":"2026-08-16T07:54:21.310Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}