eclipse-vertx/vert.x · error · IllegalArgumentException

Ping data must be exactly 8 bytes

Error message

Ping data must be exactly 8 bytes

What it means

Protocol validation in Http2MultiplexConnection.ping: an HTTP/2 PING frame carries exactly 8 bytes of opaque payload. The supplied Buffer has a different length and is rejected before a frame is written, since the peer could not parse an illegal PING.

Source

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

    return promise.future();
  }

  @Override
  public Http2Settings remoteSettings() {
    io.netty.handler.codec.http2.Http2Settings remoteSettings = handler.remoteSettings();
    return remoteSettings != null ? HttpUtils.toVertxSettings(remoteSettings) : null;
  }

  @Override
  public HttpConnection remoteSettingsHandler(Handler<HttpSettings> handler) {
    this.remoteSettingsHandler = handler;
    return this;
  }

  @Override
  public Future<Buffer> ping(Buffer data) {
    if (data.length() != 8) {
      throw new IllegalArgumentException("Ping data must be exactly 8 bytes");
    }
    long content = data.getLong(0);
    Promise<Buffer> promise = context.promise();
    Http2PingFrame pingFrame = new DefaultHttp2PingFrame(content, false);
    writeStreamFrame(pingFrame, future -> {
      if (future.isSuccess()) {
        pendingPingAcks.add(promise);
      } else {
        promise.fail(future.cause());
      }
    });
    return promise.future();
  }

  @Override
  public HttpConnection pingHandler(@Nullable Handler<Buffer> handler) {
    this.pingHandler = handler;
    return this;

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Send a Buffer of exactly 8 bytes (pad or slice your data accordingly)
2. Use Buffer.buffer(new byte[8]) for a don't-care payload

Example fix

// before
conn.ping(nonceBuffer); // arbitrary length
// after
long token = ThreadLocalRandom.current().nextLong();
conn.ping(Buffer.buffer(8).setLong(0, token));

if (data == null || data.length() != 8) throw new IllegalArgumentException("PING payload must be 8 bytes");

boolean isValidPingPayload(Buffer b) { return b != null && b.length() == 8; }

try { conn.ping(data); } catch (IllegalArgumentException e) { conn.ping(Buffer.buffer(8).setLong(0, System.nanoTime())); }

When it happens

Trigger: Calling ping() with a Buffer of length != 8 on an Http2MultiplexConnection-based client/server.

Common situations: Sharing a ping helper between HTTP/1 keep-alive payloads and HTTP/2 where sizes differ; hashing functions producing non-8-byte outputs; forgetting that getLong(0) requires 8 readable bytes.

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

• Ping data must be exactly 8 bytes
• HTTP/1.x connections don't support PING
• Invalid reset code value
• Invalid window size: ${windowSize}
• Invalid window size: ${windowSize}

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