{"record":{"id":"91407aa056a9e0ae","repo":"quarkusio/quarkus","slug":"onpingmessage-callback-must-accept-exactly-one-me","errorCode":null,"errorMessage":"@OnPingMessage callback must accept exactly one message parameter of type io.vertx.core.buffer.Buffer: ","messagePattern":"@OnPingMessage callback must accept exactly one message parameter of type io\\.vertx\\.core\\.buffer\\.Buffer: ","errorType":"validation","errorClass":"WebSocketServerException","httpStatus":null,"severity":"error","filePath":"extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/WebSocketProcessor.java","lineNumber":1094,"sourceCode":"        return \"\";\n    }\n\n    private void validateOnPingMessage(Callback callback) {\n        if (KotlinUtils.isKotlinMethod(callback.method)) {\n            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())\n                    && !callback.isKotlinSuspendFunctionReturningUnit()) {\n                throw new WebSocketServerException(\n                        \"@OnPingMessage callback must return Unit or Uni<Void>: \" + callback.asString());\n            }\n        } else {\n            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())) {\n                throw new WebSocketServerException(\n                        \"@OnPingMessage callback must return void or Uni<Void>: \" + callback.asString());\n            }\n        }\n        Type messageType = callback.argumentType(MessageCallbackArgument::isMessage);\n        if (messageType == null || !messageType.name().equals(WebSocketDotNames.BUFFER)) {\n            throw new WebSocketServerException(\n                    \"@OnPingMessage callback must accept exactly one message parameter of type io.vertx.core.buffer.Buffer: \"\n                            + callback.asString());\n        }\n    }\n\n    private void validateOnPongMessage(Callback callback) {\n        if (KotlinUtils.isKotlinMethod(callback.method)) {\n            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())\n                    && !callback.isKotlinSuspendFunctionReturningUnit()) {\n                throw new WebSocketServerException(\n                        \"@OnPongMessage callback must return Unit or Uni<Void>: \" + callback.asString());\n            }\n        } else {\n            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())) {\n                throw new WebSocketServerException(\n                        \"@OnPongMessage callback must return void or Uni<Void>: \" + callback.asString());\n            }\n        }","sourceCodeStart":1076,"sourceCodeEnd":1112,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/WebSocketProcessor.java#L1076-L1112","documentation":"An @OnPingMessage callback must take exactly one message parameter, and its type must be io.vertx.core.buffer.Buffer, since pings carry raw bytes. The processor resolves the message argument via MessageCallbackArgument::isMessage and fails the build if none matches or the type is not Buffer.","triggerScenarios":"Declaring @OnPingMessage with zero parameters, with more than one message parameter, or with a message parameter typed as String, byte[], Buffer (other), or a custom type instead of io.vertx.core.buffer.Buffer.","commonSituations":"Copying an @OnMessage(String) signature onto a ping handler; assuming ping payloads decode to text; adding extra helper parameters (headers, connection) to the callback; importing the wrong Buffer type (e.g. Netty's or java.nio's).","solutions":["Change the callback to accept exactly one io.vertx.core.buffer.Buffer parameter.","Remove extra parameters that are not supported callback arguments.","Decode the Buffer inside the method (buffer.toString(), getBytes()) if you need text/bytes.","Check imports: io.vertx.core.buffer.Buffer, not another Buffer class."],"exampleFix":"// before\n@OnPingMessage\nvoid onPing(String payload) { }\n\n// after\n@OnPingMessage\nvoid onPing(io.vertx.core.buffer.Buffer payload) { }","handlingStrategy":"validation","validationCode":"// Pre-check: exactly one io.vertx.core.buffer.Buffer parameter\nstatic void checkPingSignature(Method m) {\n    if (m.getParameterCount() != 1 || m.getParameterTypes()[0] != io.vertx.core.buffer.Buffer.class)\n        throw new IllegalStateException(\"@OnPingMessage needs exactly one io.vertx.core.buffer.Buffer param: \" + m);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Import io.vertx.core.buffer.Buffer explicitly","Never add extra parameters to ping/pong callbacks","Decode the Buffer inside the handler for text/binary needs","Keep ping and pong handler signatures identical in shape"],"tags":["quarkus","websockets-next","callback","signature","build-time"],"backgroundTag":"invalid-callback-signature","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}