What causes "Invalid reset code value" in eclipse-vertx/vert.x?

Pass only valid HTTP/2 error codes (0 to 0xFFFFFFFF, e.g. Http2Error values like 0x08 CANCEL).

eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid reset code value

Error message

Invalid reset code value

What it means

DefaultHttp2Stream.writeReset validates the RST_STREAM error code and rejects negative values. HTTP/2 reset codes (RFC 7540 section 7) are unsigned 32-bit values; a negative long cannot be encoded in the frame. Vert.x throws IllegalArgumentException immediately before scheduling the reset write.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/http2/DefaultHttp2Stream.java:433

    bytesWritten += numOfBytes;
    if (end) {
      trailersSent = true;
      StreamObserver observer = observer();
      if (observer != null) {
        observer.observeOutboundTrailers(bytesWritten);
      }
    }
    connection.writeData(id, chunk, end, promise);
  }

  @Override
  public Future<Boolean> cancel() {
    return writeReset(0x08L).map(true);
  }

  public final Future<Void> writeReset(long code) {
    if (code < 0L) {
      throw new IllegalArgumentException("Invalid reset code value");
    }
    Promise<Void> promise = context.promise();
    EventLoop eventLoop = connection.context().nettyEventLoop();
    if (eventLoop.inEventLoop()) {
      writeReset0(code, promise);
    } else {
      eventLoop.execute(() -> writeReset0(code, promise));
    }
    return promise.future();
  }

  private void writeReset0(long code, Promise<Void> promise) {
    if (trailersSent && trailersReceived) {
      promise.fail("Request ended");
    } else {
      if (reset != -1L) {
        promise.fail("Stream already reset");
      } else {

View on GitHub (pinned to fb308bd8c3)

Solutions

Pass only valid HTTP/2 error codes (0 to 0xFFFFFFFF, e.g. Http2Error values like 0x08 CANCEL).
Validate/normalize the code before calling writeReset: clamp or reject negatives.
If a sentinel is needed, use a standard code such as 0x08 (CANCEL) or 0x00 (NO_ERROR).

Example fix

// before
stream.writeReset(-1);
// after
if (code < 0) code = 0x08; // CANCEL
stream.writeReset(code);

Defensive patterns

Strategy: validation

Validate before calling

if (code < 0 || code > 0xFFFFFFFFL) throw new IllegalArgumentException("bad reset code");

Type guard

boolean isValidResetCode(long c) { return c >= 0 && c <= 0xFFFFFFFFL; }

Try / catch

try { stream.writeReset(code); } catch (IllegalArgumentException e) { stream.writeReset(0x08); }

Prevention

Use named constants (Http2Error.CANCEL etc.) instead of raw numbers
Validate codes parsed from user input
Never use -1 as sentinel for error codes
Add range assertions in code-producing logic

When it happens

Trigger: Calling stream.writeReset(code) with a negative long, e.g. passing -1 as a sentinel or an unvalidated integer parsed from config/input.

Common situations: Application-defined error codes computed by subtraction that underflow; forwarding untrusted reset codes from user input; using Java int codes cast with a sign issue.

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

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