eclipse-vertx/vert.x · error · IOException

Size exceed allowed maximum capacity

Error message

Size exceed allowed maximum capacity

What it means

NettyFileUpload.checkSize is the guard called as each chunk of a multipart/form-data file upload is accumulated in Vert.x. When the running total of upload bytes exceeds the configured maxSize (and maxSize is not negative/disabled), it throws this IOException to abort the upload before memory/disk is exhausted. The library throws it to let applications enforce upload size limits.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/NettyFileUpload.java:188

  @Override
  public long length() {
    return size;
  }

  @Override
  public void delete() {
    throw new UnsupportedOperationException();
  }

  @Override
  public long definedLength() {
    return size;
  }

  @Override
  public void checkSize(long newSize) throws IOException {
    if (maxSize >= 0 && newSize > maxSize) {
      throw new IOException("Size exceed allowed maximum capacity");
    }
  }

  @Override
  public long getMaxSize() {
    return maxSize;
  }

  @Override
  public void setMaxSize(long maxSize) {
    this.maxSize = maxSize;
  }

  @Override
  public byte[] get() throws IOException {
    throw new UnsupportedOperationException();
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Increase the allowed upload size, e.g. via setUploadsDirectory/maxSize on the multipart config or a BodyLimitHandler with a larger limit
2. Set maxSize to -1 only if you truly want unlimited uploads (avoid in production)
3. Limit request size at the proxy/load balancer so oversized uploads are rejected before reaching Vert.x
4. Catch the IOException and respond 413 Payload Too Large with a clear message to the client

Example fix

// before
router.route().handler(BodyHandler.create().setBodyLimit(1024 * 1024)); // 1MB, too small for uploads
// after
router.route().handler(BodyHandler.create().setBodyLimit(50L * 1024 * 1024)); // 50MB

long declaredSize = getContentLengthOrZero(request); // compare against configured maxSize before accepting the stream
if (declaredSize > MAX_UPLOAD) { respond413(); return; }

try {
  request.bodyHandler(buffer -> { /* accumulate */ });
} catch (IOException e) {
  if (e.getMessage().contains("Size exceed")) {
    ctx.fail(413, e); // Payload Too Large
  } else {
    ctx.fail(e);
  }
}

When it happens

Trigger: A client uploads a file larger than the maxSize configured on the BodyLimitHandler / multipart upload (maxSize >= 0 && newSize > maxSize). The check fires during Attribute/FileUpload content streaming, e.g. in route.bodyHandler or multipart form parsing when a single file's size exceeds the limit.

Common situations: File-upload endpoints with a max upload size where users send oversized files; a limit configured too low for legitimate PDFs/videos; proxy chains that bypass a smaller upstream limit; after upgrading, limits that were previously disabled (-1) are now enforced.

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

• Multipart form requires multipart/form-data content type ins
• Request must have a content-type header to decode a multipar
• Request must have a valid content-type header to decode a mu
• Request method must be one of POST, PUT, PATCH or DELETE to
• Request must have a content-type header to decode a multipar

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