eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid window size: ${windowSize}

Error message

Invalid window size: ${windowSize}

What it means

HttpConnection.setWindowSize on the standard HTTP/2 connection implementation rejects window sizes <= 0. The connection-level flow-control window must be a positive number of bytes; Vert.x validates before computing the delta to apply to Netty's flow controller.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/http2/codec/Http2ConnectionImpl.java:321

      data = safeBuffer(data);
      Buffer buff = BufferInternal.buffer(data);
      stream.onData(buff);
      if (endOfStream) {
        stream.onTrailers();
      }
    }
    return padding;
  }

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

  @Override
  public HttpConnection setWindowSize(int windowSize) {
    if (windowSize <= 0) {
      throw new IllegalArgumentException("Invalid window size: " + windowSize);
    }
    try {
      io.netty.handler.codec.http2.Http2Stream stream = handler.encoder().connection().connectionStream();
      int delta = windowSize - this.windowSize;
      handler.decoder().flowController().incrementWindowSize(stream, delta);
      this.windowSize = windowSize;
      return this;
    } catch (Http2Exception e) {
      throw new VertxException(e);
    }
  }

  @Override
  public HttpVersion protocolVersion() {
    return HttpVersion.HTTP_2;
  }

  @Override

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a positive int, e.g. setWindowSize(65535) or larger for high-throughput servers.
2. Validate configuration before applying: if (configured <= 0) use a sane default like 65535.
3. Remember this sets an absolute window size, not an increment; compute the desired total first.

Example fix

// before
conn.setWindowSize(config.getWindowSize()); // may be 0
// after
int ws = config.getWindowSize() > 0 ? config.getWindowSize() : 65535;
conn.setWindowSize(ws);

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 connection.setWindowSize(0) or a negative value, often from a user-supplied config value for the HTTP/2 connection window.

Common situations: Config files where the window size is 0 ('disabled' intended) or a negative default; parsing settings from environment variables without validation; confusing window size with increment semantics.

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/bfe244600490d29c. Report an issue: GitHub.