eclipse-vertx/vert.x · error · java.lang.UnsupportedOperationException

HTTP/1.x connections don't support PING

Error message

HTTP/1.x connections don't support PING

What it means

Thrown by Http1Connection.pingHandler(Handler<Buffer>) because HTTP/1.x has no PING frame; application-level connection keepalive pings are an HTTP/2 feature. The HTTP/1.x implementation rejects handler registration with UnsupportedOperationException, as it does for the other HTTP/2-only operations on this class.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/http1/Http1Connection.java:137

  @Override
  public Future<Void> updateSettings(HttpSettings settings) {
    throw new UnsupportedOperationException("HTTP/1.x connections don't support SETTINGS");
  }

  @Override
  public Http2Settings remoteSettings() {
    throw new UnsupportedOperationException("HTTP/1.x connections don't support SETTINGS");
  }

  @Override
  public HttpConnection remoteSettingsHandler(Handler<HttpSettings> handler) {
    throw new UnsupportedOperationException("HTTP/1.x connections don't support SETTINGS");
  }

  @Override
  public HttpConnection pingHandler(@Nullable Handler<Buffer> handler) {
    throw new UnsupportedOperationException("HTTP/1.x connections don't support PING");
  }

  @Override
  public Future<Buffer> ping(Buffer data) {
    throw new UnsupportedOperationException("HTTP/1.x connections don't support PING");
  }

  @Override
  protected long sizeof(Object obj) {
    // https://github.com/netty/netty/issues/12708
    // try first Netty HTTP singleton types, without any instanceof/checkcast bytecodes
    if (obj == Unpooled.EMPTY_BUFFER || obj == LastHttpContent.EMPTY_LAST_CONTENT) {
      return 0;
    }
    // try known vertx (non-interface) types: bi-morphic
    if (obj instanceof VertxAssembledHttpResponse) {
      return ((VertxAssembledHttpResponse) obj).content().readableBytes();
    }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Register pingHandler only when the connection is HTTP/2; for HTTP/1.x use TCP-level or request-based keepalive checks instead.
2. Guard registration with try/catch (UnsupportedOperationException) so instrumentation code is protocol-agnostic.
3. Enable HTTP/2 negotiation (ALPN h2 over TLS, or h2c prior knowledge) if ping-based keepalive/RTT measurement is required.
4. For HTTP/1.x liveness, implement an application-level heartbeat (small periodic request) rather than relying on PING frames.

Example fix

// before
conn.pingHandler(pong -> recordRtt());

// after
try {
  conn.pingHandler(pong -> recordRtt());
} catch (UnsupportedOperationException e) {
  // HTTP/1.x: use a lightweight periodic request as keepalive instead
}

if (request.version() == HttpVersion.HTTP_2) {
  conn.pingHandler(handler);
}

static boolean supportsPing(HttpConnection c) {
  return !(c instanceof io.vertx.core.http.impl.http1.Http1Connection);
}

try {
  conn.pingHandler(pong -> recordRtt());
} catch (UnsupportedOperationException e) {
  // HTTP/1.x: fall back to periodic lightweight request keepalive
}

When it happens

Trigger: Calling conn.pingHandler(handler) on an HTTP/1.x connection to observe peer keepalive pings or measure RTT — for example in shared connection health-check code that registers ping handlers for every connection independent of protocol.

Common situations: Keepalive/latency-monitoring middleware built for HTTP/2 applied to mixed-protocol deployments; clients silently downgraded to HTTP/1.1 because the server or an intermediary lacks h2 support; health-check frameworks instrumenting pooled HTTP/1.1 connections; migration from Netty/other HTTP/2 stacks where ping handling existed for all versions.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• HTTP/1.x connections don't support SETTINGS
• Cannot write an HTTP/2 frame over an HTTP/1.x connection
• http2MaxPoolSize must be > 0
• HTTP/1.x connections don't support GOAWAY
• 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/938ebf707585802b. Report an issue: GitHub.