quarkusio/quarkus · error · WebSocketServerException

@OnPongMessage callback must accept exactly one message para

Error message

@OnPongMessage callback must accept exactly one message parameter of type io.vertx.core.buffer.Buffer: 

What it means

Quarkus websockets-next requires an @OnPongMessage callback to accept exactly one message parameter of type io.vertx.core.buffer.Buffer — pong frames carry raw binary data, so only Buffer is supported. The build fails if the callback takes zero parameters, multiple parameters, or a message parameter of a different type.

Source

Thrown at extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/WebSocketProcessor.java:1115

        }
    }

    private void validateOnPongMessage(Callback callback) {
        if (KotlinUtils.isKotlinMethod(callback.method)) {
            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())
                    && !callback.isKotlinSuspendFunctionReturningUnit()) {
                throw new WebSocketServerException(
                        "@OnPongMessage callback must return Unit or Uni<Void>: " + callback.asString());
            }
        } else {
            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())) {
                throw new WebSocketServerException(
                        "@OnPongMessage callback must return void or Uni<Void>: " + callback.asString());
            }
        }
        Type messageType = callback.argumentType(MessageCallbackArgument::isMessage);
        if (messageType == null || !messageType.name().equals(WebSocketDotNames.BUFFER)) {
            throw new WebSocketServerException(
                    "@OnPongMessage callback must accept exactly one message parameter of type io.vertx.core.buffer.Buffer: "
                            + callback.asString());
        }
    }

    private void validateOnClose(Callback callback) {
        if (KotlinUtils.isKotlinMethod(callback.method)) {
            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())
                    && !callback.isKotlinSuspendFunctionReturningUnit()) {
                throw new WebSocketServerException(
                        "@OnClose callback must return Unit or Uni<Void>: " + callback.asString());
            }
        } else {
            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())) {
                throw new WebSocketServerException(
                        "@OnClose callback must return void or Uni<Void>: " + callback.asString());
            }
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Declare exactly one message parameter of type io.vertx.core.buffer.Buffer
2. If you need text, convert inside the method: data.toString() or data.getBytes()
3. Remove extra parameters or use supported injected types per the callback-arguments rules (the message slot itself must be Buffer)

Example fix

// before
@OnPongMessage
void onPong(String data) { }

// after
import io.vertx.core.buffer.Buffer;
@OnPongMessage
void onPong(Buffer data) { }

// Verify the pong callback signature
@OnPongMessage void onPong(io.vertx.core.buffer.Buffer data) {} // only Buffer allowed

When it happens

Trigger: @OnPongMessage method with no parameters; @OnPongMessage with a String, byte[], or JsonObject message parameter; @OnPongMessage with extra parameters that are not recognized as message-typed (only one isMessage argument allowed and it must be Buffer).

Common situations: Developer assumes pong callbacks mirror @OnTextMessage and declares String or byte[] payload; developer omits the parameter entirely; a refactor changes the parameter type.

Related errors

• @OnPongMessage callback must return void or Uni<Void>:
• @OnClose callback must return void or Uni<Void>:
• @OnError callback must accept exactly one error parameter; f
• @%s callback may accept at most 1 message parameter; found %
• @%s callback must not accept a message parameter; found %s:

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/40b49439a8c6e80d. Report an issue: GitHub.