{"record":{"id":"70d95861b2faa863","repo":"quarkusio/quarkus","slug":"websocket-callback-method-may-not-accept-websocke","errorCode":null,"errorMessage":"@WebSocket callback method may not accept WebSocketClientConnection","messagePattern":"@WebSocket callback method may not accept WebSocketClientConnection","errorType":"exception","errorClass":"WebSocketException","httpStatus":null,"severity":"error","filePath":"extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/ConnectionCallbackArgument.java","lineNumber":19,"sourceCode":"package io.quarkus.websockets.next.deployment;\n\nimport org.jboss.jandex.DotName;\n\nimport io.quarkus.gizmo2.Expr;\nimport io.quarkus.websockets.next.WebSocketException;\nimport io.quarkus.websockets.next.deployment.Callback.Target;\n\nclass ConnectionCallbackArgument implements CallbackArgument {\n\n    @Override\n    public boolean matches(ParameterContext context) {\n        DotName paramTypeName = context.parameter().type().name();\n        if (context.callbackTarget() == Target.SERVER) {\n            if (WebSocketDotNames.WEB_SOCKET_CONNECTION.equals(paramTypeName)\n                    || WebSocketDotNames.CONNECTION.equals(paramTypeName)) {\n                return true;\n            } else if (WebSocketDotNames.WEB_SOCKET_CLIENT_CONNECTION.equals(paramTypeName)) {\n                throw new WebSocketException(\"@WebSocket callback method may not accept WebSocketClientConnection\");\n            }\n        } else if (context.callbackTarget() == Target.CLIENT) {\n            if (WebSocketDotNames.WEB_SOCKET_CLIENT_CONNECTION.equals(paramTypeName)\n                    || WebSocketDotNames.CONNECTION.equals(paramTypeName)) {\n                return true;\n            } else if (WebSocketDotNames.WEB_SOCKET_CONNECTION.equals(paramTypeName)) {\n                throw new WebSocketException(\"@WebSocketClient callback method may not accept WebSocketConnection\");\n            }\n        }\n        return false;\n    }\n\n    @Override\n    public Expr get(InvocationBytecodeContext context) {\n        return context.getConnection();\n    }\n\n}","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/ConnectionCallbackArgument.java#L1-L37","documentation":"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.","triggerScenarios":"Declaring a method parameter of type WebSocketClientConnection inside a @WebSocket (server) endpoint callback such as @OnOpen, @OnMessage, @OnClose or @OnError.","commonSituations":"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.","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"],"exampleFix":"// before (@WebSocket endpoint)\n@OnMessage\nvoid onMessage(WebSocketClientConnection conn, String msg) { }\n// after\n@OnMessage\nvoid onMessage(WebSocketConnection conn, String msg) { }","handlingStrategy":"type-guard","validationCode":"// Endpoint-side check\nif (method.getParameterTypes() contains WebSocketClientConnection.class)\n    throw new IllegalStateException(\"use WebSocketConnection in server endpoints\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["quarkus","websockets-next","build-time","type-mismatch"],"backgroundTag":"websocket-connection-type-mismatch","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}