eclipse-vertx/vert.x · error · UnsupportedOperationException

Cannot write frame with HTTP/1.x

Error message

Cannot write frame with HTTP/1.x 

What it means

HttpClientRequestPushPromise.writeCustomFrame throws UnsupportedOperationException because the underlying connection is HTTP/1.x, which does not support HTTP/2 custom frames. Writing raw frames is only meaningful on HTTP/2 (or HTTP/3) connections.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/HttpClientRequestPushPromise.java:227

  @Override
  public Future<Void> end() {
    throw new IllegalStateException();
  }

  @Override
  public boolean writeQueueFull() {
    throw new IllegalStateException();
  }

  @Override
  public StreamPriority getStreamPriority() {
    return stream.priority();
  }

  @Override
  public Future<Void> writeCustomFrame(int type, int flags, Buffer payload) {
    throw new UnsupportedOperationException("Cannot write frame with HTTP/1.x ");
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Guard the call with a check that the connection/protocol is HTTP/2 (HttpVersion.HTTP_2) before calling writeCustomFrame
2. Remove the writeCustomFrame call when targeting HTTP/1.x servers
3. Upgrade the client connection to HTTP/2 (ALPN, TLS) if custom frames are required

Example fix

// before
request.writeCustomFrame(0x40, 0, payload);
// after
if (request.version() == HttpVersion.HTTP_2) {
  request.writeCustomFrame(0x40, 0, payload);
}

if (request.version() != HttpVersion.HTTP_2) {
  throw new UnsupportedOperationException("writeCustomFrame requires HTTP/2");
}

boolean supportsCustomFrames(HttpClientRequest req) {
  return req.version() == HttpVersion.HTTP_2 || req.version() == HttpVersion.HTTP_3;
}

try {
  request.writeCustomFrame(type, flags, payload);
} catch (UnsupportedOperationException e) {
  // fall back: encode data as a normal write or skip on HTTP/1.x
}

When it happens

Trigger: Calling writeCustomFrame(type, flags, payload) on a push promise/request obtained from an HTTP/1.1 connection.

Common situations: Code written for HTTP/2 that sends custom frames being reused against an HTTP/1.x server; protocol-agnostic pipelines that unconditionally call writeCustomFrame.

Related errors

• HTTP/1.x connections don't support GOAWAY
• Change group of file not supported
• http2MaxPoolSize must be > 0
• Only socket address are currently supported
• A push response cannot promise another push

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