quarkusio/quarkus · error · WebSocketServerException

@OnPongMessage callback must return void or Uni<Void>:

Error message

@OnPongMessage callback must return void or Uni<Void>: 

What it means

Quarkus websockets-next validates at build time that a method annotated with @OnPongMessage returns either void or Uni<Void> (or Unit for Kotlin suspend functions). A pong callback must not produce a value, since pong handling has no result to deliver back to the caller. The build fails with WebSocketServerException naming the offending callback via asString().

Source

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

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

View on GitHub (pinned to e1c734241f)

Solutions

1. Change the @OnPongMessage method return type to void
2. If async handling is needed, return Uni<Void> (Mutiny) and ensure all paths resolve with null
3. For Kotlin suspend functions, return Unit (suspend function returning Unit is accepted)
4. Move any value-producing logic into a separate method and keep the callback side-effect only

Example fix

// before
@OnPongMessage
String onPong(Buffer data) { return data.toString(); }

// after
@OnPongMessage
void onPong(Buffer data) { log.debug("pong: " + data); }

// Check before annotating: all @OnPongMessage methods return void or Uni<Void>
for (Method m : MyWebSocket.class.getDeclaredMethods()) {
    if (m.isAnnotationPresent(OnPongMessage.class)) {
        boolean ok = m.getReturnType().equals(void.class)
            || UniVoidChecker.isUniVoid(m.getGenericReturnType());
        if (!ok) throw new IllegalStateException(m + " must return void or Uni<Void>");
    }
}

When it happens

Trigger: Annotating a method with @OnPongMessage whose return type is something other than void or Uni<Void> (non-Kotlin), e.g. returning String, boolean, Response, or Uni<String>.

Common situations: Developer copies an @OnTextMessage callback signature (which may return values) and renames the annotation to @OnPongMessage; returning a status flag from pong handling; IDE-generated stubs returning a value.

Related errors

• @OnPongMessage callback must accept exactly one message para
• @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/088330efd9d6203d. Report an issue: GitHub.