eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid window size: ${windowSize}

Error message

Invalid window size: ${windowSize}

What it means

Identical validation to Http2ConnectionImpl: the multiplexed HTTP/2 connection's setWindowSize requires windowSize > 0 because flow-control windows are unsigned positive byte counts. Thrown before applying the increment to the underlying handler.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/http2/multiplex/Http2MultiplexConnection.java:302

  @Override
  public Http2MultiplexConnection closeHandler(Handler<Void> handler) {
    return (Http2MultiplexConnection) super.closeHandler(handler);
  }

  @Override
  public Http2Settings settings() {
    return HttpUtils.toVertxSettings(handler.localSettings());
  }

  @Override
  public int getWindowSize() {
    return windowSize;
  }

  @Override
  public HttpConnection setWindowSize(int windowSize) {
    if (windowSize <= 0) {
      throw new IllegalArgumentException("Invalid window size: " + windowSize);
    }
    try {
      int windowSizeIncrement = windowSize - this.windowSize;
      handler.incrementWindowsSize(windowSizeIncrement);
      this.windowSize = windowSize;
      return this;
    } catch (Http2Exception e) {
      throw new VertxException(e);
    }
  }

  @Override
  public Future<Void> updateSettings(HttpSettings settings) {
    PromiseInternal<Void> promise = context.promise();
    handler.writeSettings(HttpUtils.fromVertxSettings((Http2Settings) settings), promise);
    return promise.future();
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use a positive value, e.g. setWindowSize(65535) or larger.
2. Clamp user/config input: windowSize = Math.max(1, configured).
3. Confirm you are setting the connection window, not the stream window, and that semantics require > 0.

Example fix

// before
conn.setWindowSize(opts.windowSize()); // 0 possible
// after
conn.setWindowSize(Math.max(1, opts.windowSize()));

if (windowSize <= 0) throw new IllegalArgumentException("windowSize must be > 0");

boolean validWindowSize(int ws) { return ws > 0; }

try { conn.setWindowSize(ws); } catch (IllegalArgumentException e) { conn.setWindowSize(65535); }

When it happens

Trigger: Calling HttpConnection.setWindowSize(0) or negative on a connection created via Http2MultiplexConnection (HTTP/2 with multiplexing), typically from unvalidated configuration.

Common situations: Zero used as 'default/unlimited' in config; signed arithmetic producing negative sizes; differences between stream window settings (which allow different bounds) and connection window.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Invalid window size: ${windowSize}
• Invalid reset code value
• Ping data must be exactly 8 bytes
• Ping data must be exactly 8 bytes
• http2MaxPoolSize must be > 0

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