quarkusio/quarkus · error · WebSocketServerException

@OnPingMessage callback must accept exactly one message para

Error message

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

What it means

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.

Source

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

        return "";
    }

    private void validateOnPingMessage(Callback callback) {
        if (KotlinUtils.isKotlinMethod(callback.method)) {
            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())
                    && !callback.isKotlinSuspendFunctionReturningUnit()) {
                throw new WebSocketServerException(
                        "@OnPingMessage callback must return Unit or Uni<Void>: " + callback.asString());
            }
        } else {
            if (!callback.isReturnTypeVoid() && !isUniVoid(callback.returnType())) {
                throw new WebSocketServerException(
                        "@OnPingMessage 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(
                    "@OnPingMessage callback must accept exactly one message parameter of type io.vertx.core.buffer.Buffer: "
                            + callback.asString());
        }
    }

    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());
            }
        }

View on GitHub (pinned to e1c734241f)

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.

Example fix

// before
@OnPingMessage
void onPing(String payload) { }

// after
@OnPingMessage
void onPing(io.vertx.core.buffer.Buffer payload) { }

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check: exactly one io.vertx.core.buffer.Buffer parameter
static void checkPingSignature(Method m) {
    if (m.getParameterCount() != 1 || m.getParameterTypes()[0] != io.vertx.core.buffer.Buffer.class)
        throw new IllegalStateException("@OnPingMessage needs exactly one io.vertx.core.buffer.Buffer param: " + m);
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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).

Related errors

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