quarkusio/quarkus · error · WebSocketException

@WebSocket callback method may not accept WebSocketClientCon

Error message

@WebSocket callback method may not accept WebSocketClientConnection

What it means

In websockets-next, a server-side @WebSocket endpoint callback may inject WebSocketConnection (or io.quarkus.websockets.next.WebSocketConnection) but must not use the client connection type WebSocketClientConnection. The ConnectionCallbackArgument matcher detects this mix-up during build and aborts with WebSocketException.

Source

Thrown at extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/ConnectionCallbackArgument.java:19

package io.quarkus.websockets.next.deployment;

import org.jboss.jandex.DotName;

import io.quarkus.gizmo2.Expr;
import io.quarkus.websockets.next.WebSocketException;
import io.quarkus.websockets.next.deployment.Callback.Target;

class ConnectionCallbackArgument implements CallbackArgument {

    @Override
    public boolean matches(ParameterContext context) {
        DotName paramTypeName = context.parameter().type().name();
        if (context.callbackTarget() == Target.SERVER) {
            if (WebSocketDotNames.WEB_SOCKET_CONNECTION.equals(paramTypeName)
                    || WebSocketDotNames.CONNECTION.equals(paramTypeName)) {
                return true;
            } else if (WebSocketDotNames.WEB_SOCKET_CLIENT_CONNECTION.equals(paramTypeName)) {
                throw new WebSocketException("@WebSocket callback method may not accept WebSocketClientConnection");
            }
        } else if (context.callbackTarget() == Target.CLIENT) {
            if (WebSocketDotNames.WEB_SOCKET_CLIENT_CONNECTION.equals(paramTypeName)
                    || WebSocketDotNames.CONNECTION.equals(paramTypeName)) {
                return true;
            } else if (WebSocketDotNames.WEB_SOCKET_CONNECTION.equals(paramTypeName)) {
                throw new WebSocketException("@WebSocketClient callback method may not accept WebSocketConnection");
            }
        }
        return false;
    }

    @Override
    public Expr get(InvocationBytecodeContext context) {
        return context.getConnection();
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

Replace the parameter type with WebSocketConnection in the server-side callback
Move the method to a @WebSocketClient endpoint if client connection semantics are intended
If both kinds share a base class, parameterize the connection type or split the base class

Example fix

// before (@WebSocket endpoint)
@OnMessage
void onMessage(WebSocketClientConnection conn, String msg) { }
// after
@OnMessage
void onMessage(WebSocketConnection conn, String msg) { }

Defensive patterns

Strategy: type-guard

Validate before calling

// Endpoint-side check
if (method.getParameterTypes() contains WebSocketClientConnection.class)
    throw new IllegalStateException("use WebSocketConnection in server endpoints");

Prevention

Never share callback signatures verbatim between server and client endpoints
Watch IDE auto-imports of the connection type
Use WebSocketConnection in server code, WebSocketClientConnection in clients

When it happens

Trigger: Declaring a method parameter of type WebSocketClientConnection inside a @WebSocket (server) endpoint callback such as @OnOpen, @OnMessage, @OnClose or @OnError.

Common situations: Copy-pasting a callback method from a @WebSocketClient class into a server endpoint (or vice versa) without adjusting the connection parameter type; sharing a common base class of endpoints that references the wrong connection type.

Related errors

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