{"record":{"id":"51cdc0fede3d3970","repo":"eclipse-vertx/vert.x","slug":"cannot-write-frame-with-http-1-x","errorCode":null,"errorMessage":"Cannot write frame with HTTP/1.x ","messagePattern":"Cannot write frame with HTTP/1\\.x ","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/HttpClientRequestPushPromise.java","lineNumber":227,"sourceCode":"\n  @Override\n  public Future<Void> end() {\n    throw new IllegalStateException();\n  }\n\n  @Override\n  public boolean writeQueueFull() {\n    throw new IllegalStateException();\n  }\n\n  @Override\n  public StreamPriority getStreamPriority() {\n    return stream.priority();\n  }\n\n  @Override\n  public Future<Void> writeCustomFrame(int type, int flags, Buffer payload) {\n    throw new UnsupportedOperationException(\"Cannot write frame with HTTP/1.x \");\n  }\n}\n","sourceCodeStart":209,"sourceCodeEnd":230,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/HttpClientRequestPushPromise.java#L209-L230","documentation":"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.","triggerScenarios":"Calling writeCustomFrame(type, flags, payload) on a push promise/request obtained from an HTTP/1.1 connection.","commonSituations":"Code written for HTTP/2 that sends custom frames being reused against an HTTP/1.x server; protocol-agnostic pipelines that unconditionally call writeCustomFrame.","solutions":["Guard the call with a check that the connection/protocol is HTTP/2 (HttpVersion.HTTP_2) before calling writeCustomFrame","Remove the writeCustomFrame call when targeting HTTP/1.x servers","Upgrade the client connection to HTTP/2 (ALPN, TLS) if custom frames are required"],"exampleFix":"// before\nrequest.writeCustomFrame(0x40, 0, payload);\n// after\nif (request.version() == HttpVersion.HTTP_2) {\n  request.writeCustomFrame(0x40, 0, payload);\n}","handlingStrategy":"validation","validationCode":"if (request.version() != HttpVersion.HTTP_2) {\n  throw new UnsupportedOperationException(\"writeCustomFrame requires HTTP/2\");\n}","typeGuard":"boolean supportsCustomFrames(HttpClientRequest req) {\n  return req.version() == HttpVersion.HTTP_2 || req.version() == HttpVersion.HTTP_3;\n}","tryCatchPattern":"try {\n  request.writeCustomFrame(type, flags, payload);\n} catch (UnsupportedOperationException e) {\n  // fall back: encode data as a normal write or skip on HTTP/1.x\n}","preventionTips":["Check the negotiated protocol before using HTTP/2-only APIs","Branch pipelines by HttpVersion early","Enable ALPN/TLS when custom frames are required"],"tags":["http2","http1x","unsupported","frames"],"backgroundTag":"operation-not-supported","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}