quarkusio/quarkus · error · WebSocketException

@WebSocketClient callback method may not accept WebSocketCon

Error message

@WebSocketClient callback method may not accept WebSocketConnection

What it means

The mirror case of the server-side rule: a @WebSocketClient callback may inject WebSocketClientConnection (or Connection) but must not accept the server-side WebSocketConnection type. The build fails with WebSocketException when the ConnectionCallbackArgument matcher sees the wrong type on the client target.

Source

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

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

Change the parameter to WebSocketClientConnection in the client callback
Move the method to a server @WebSocket endpoint if server connection semantics are intended
Check imports in shared classes so the correct connection type is used per endpoint kind

Example fix

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

Defensive patterns

Strategy: type-guard

Validate before calling

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

Prevention

Double-check imports when copying code from server endpoints
Keep separate base classes for client and server callbacks

When it happens

Trigger: Declaring a parameter of type WebSocketConnection inside a @WebSocketClient endpoint callback.

Common situations: Copy-pasting server endpoint callbacks into a client class; IDE auto-import picking the wrong WebSocketConnection class; shared callback base classes reused between server and client endpoints.

Related errors

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