{"record":{"id":"21468af9746524d8","repo":"apache/druid","slug":"cannot-map-region-larger-than-d-bytes","errorCode":null,"errorMessage":"Cannot map region larger than %,d bytes","messagePattern":"Cannot map region larger than %,d bytes","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/java/util/common/FileUtils.java","lineNumber":203,"sourceCode":"  /**\n   * Fully maps a file read-only in to memory as per\n   * {@link FileChannel#map(FileChannel.MapMode, long, long)}.\n   *\n   * @param file   the file to map\n   * @param offset starting offset for the mmap\n   * @param length length for the mmap\n   *\n   * @return a {@link MappedByteBufferHandler}, wrapping a read-only buffer reflecting {@code file}\n   *\n   * @throws FileNotFoundException    if the {@code file} does not exist\n   * @throws IOException              if an I/O error occurs\n   * @throws IllegalArgumentException if length is greater than {@link Integer#MAX_VALUE}\n   * @see FileChannel#map(FileChannel.MapMode, long, long)\n   */\n  public static MappedByteBufferHandler map(File file, long offset, long length) throws IOException\n  {\n    if (length > Integer.MAX_VALUE) {\n      throw new IAE(\"Cannot map region larger than %,d bytes\", Integer.MAX_VALUE);\n    }\n\n    try (final RandomAccessFile randomAccessFile = new RandomAccessFile(file, \"r\");\n         final FileChannel channel = randomAccessFile.getChannel()) {\n      final MappedByteBuffer mappedByteBuffer = channel.map(FileChannel.MapMode.READ_ONLY, offset, length);\n      return new MappedByteBufferHandler(mappedByteBuffer);\n    }\n  }\n\n  /**\n   * Fully maps a file read-only in to memory as per\n   * {@link FileChannel#map(FileChannel.MapMode, long, long)}.\n   *\n   * @param randomAccessFile the file to map. The file will not be closed.\n   * @param offset           starting offset for the mmap\n   * @param length           length for the mmap\n   *\n   * @return a {@link MappedByteBufferHandler}, wrapping a read-only buffer reflecting {@code randomAccessFile}","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/java/util/common/FileUtils.java#L185-L221","documentation":"FileUtils.map(File, long, long) memory-maps a file region via FileChannel.map, but MappedByteBuffer is index-based and cannot exceed Integer.MAX_VALUE bytes. Any request for a larger region is rejected upfront with IllegalArgumentException.","triggerScenarios":"Calling FileUtils.map(file, offset, length) with length > Integer.MAX_VALUE (2,147,483,647 bytes).","commonSituations":"Mapping large segment files (multi-GB) whole; computing length from file size without a 2GB guard; legacy code written when files were small.","solutions":["Map the file in chunks of at most Integer.MAX_VALUE bytes and process sequentially","Use FileChannel direct reads (ByteBuffer in a loop) instead of mmap for large regions","Use the long-typed reading APIs (e.g. FileUtils.map with wrapped handler loops or java.nio channels)","Reduce the requested offset/length to a region under 2GB"],"exampleFix":"// before\nMappedByteBufferHandler h = FileUtils.map(file, 0, file.length());\n// after\nlong remaining = file.length();\nlong offset = 0;\nwhile (remaining > 0) {\n  long chunk = Math.min(remaining, Integer.MAX_VALUE);\n  try (MappedByteBufferHandler h = FileUtils.map(file, offset, chunk)) {\n    process(h.getBuffer());\n  }\n  offset += chunk;\n  remaining -= chunk;\n}","handlingStrategy":"validation","validationCode":"if (length > Integer.MAX_VALUE) {\n  throw new IllegalArgumentException(\"Use chunked mapping for \" + length + \" bytes\");\n}","typeGuard":null,"tryCatchPattern":"try (MappedByteBufferHandler h = FileUtils.map(file, offset, length)) {\n  process(h.getBuffer());\n} catch (IllegalArgumentException e) {\n  // fall back to chunked/stream reading\n}","preventionTips":["Never pass file.length() directly as length; clamp to Integer.MAX_VALUE","Design readers around chunked mapping from the start","Prefer FileChannel.read streams for files that may exceed 2GB","Add unit tests with files >2GB (or mocked lengths) for mapping code"],"tags":["io","mmap","limit-exceeded"],"backgroundTag":"file-size-limit-exceeded","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}