eclipse-vertx/vert.x · error · OutOfMemoryError

File is too big

Error message

File is too big

What it means

Thrown (deliberately as OutOfMemoryError, mirroring what Files.readAllBytes would induce) when readFile attempts to load a file larger than Integer.MAX_VALUE bytes into a Buffer. Vert.x buffers are int-indexed, so files over ~2GB cannot be read whole.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/file/impl/FileSystemImpl.java:859

          }
        } catch (IOException e) {
          throw new FileSystemException(getFolderAccessErrorMessage("read", p), e);
        }
      }
    };
  }

  private BlockingAction<Buffer> readFileInternal(String path) {
    Objects.requireNonNull(path);
    return new BlockingAction<Buffer>() {
      public Buffer perform() {
        try {
          Path target = resolveFile(path).toPath();
          try (FileChannel fc = FileChannel.open(target, StandardOpenOption.READ)) {
            long size = fc.size();
            if (size > (long) Integer.MAX_VALUE) {
              // Throwing OOM as Files#readAllLines would in this case
              throw new OutOfMemoryError("File is too big");
            }
            int len = (int) size;
            BufferInternal res = BufferInternal.buffer(len);
            res.unwrap().writeBytes(fc, 0, len);
            return res;
          }
        } catch (IOException e) {
          throw new FileSystemException(getFileAccessErrorMessage("read", path), e);
        }
      }
    };
  }

  private BlockingAction<Void> writeFileInternal(String path, Buffer data) {
    Objects.requireNonNull(path);
    Objects.requireNonNull(data);
    return new BlockingAction<Void>() {
      public Void perform() {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use FileSystem.open with OpenOptions read+buffer and stream the file via AsyncFile in chunks
2. Use FileSystem.readFile only for files known to be small; check size first with FileSystem.props(path).size()
3. Process the file line-by-line or block-by-block rather than materializing it in memory

Example fix

// before
vertx.fileSystem().readFile("huge.dat");
// after
vertx.fileSystem().open("huge.dat", new OpenOptions().setRead(true))
  .onSuccess(file -> file.pipeTo(readStream -> ...)); // stream in chunks

io.vertx.core.file.FileProps props = vertx.fileSystem().propsBlocking(path);
if (props.size() > Integer.MAX_VALUE) {
  throw new IllegalStateException("File too large to buffer: " + path);
}

try {
  fs.readFile(path);
} catch (OutOfMemoryError e) {
  if ("File is too big".equals(e.getMessage())) {
    // fall back to streaming via AsyncFile
  }
}

When it happens

Trigger: Calling FileSystem.readFile(path) on a file whose size exceeds 2,147,483,647 bytes.

Common situations: Reading large log files, data exports, or video/binary assets with readFile instead of streaming them via openFile/AsyncFile.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• Failed to chmod ${path}
• Change group of file not supported
• Accessed denied for chown on ${path}
• Failed to crown ${path}
• Failed to analyse ${path}

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/0a12df42acc5abc1. Report an issue: GitHub.