{"record":{"id":"ee763e8e520914f2","repo":"quarkusio/quarkus","slug":"websocketclient-callback-method-may-not-accept-we","errorCode":null,"errorMessage":"@WebSocketClient callback method may not accept WebSocketConnection","messagePattern":"@WebSocketClient callback method may not accept WebSocketConnection","errorType":"exception","errorClass":"WebSocketException","httpStatus":null,"severity":"error","filePath":"extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/ConnectionCallbackArgument.java","lineNumber":26,"sourceCode":"\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}\n","sourceCodeStart":8,"sourceCodeEnd":38,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/ConnectionCallbackArgument.java#L8-L38","documentation":"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.","triggerScenarios":"Declaring a parameter of type WebSocketConnection inside a @WebSocketClient endpoint callback.","commonSituations":"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.","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"],"exampleFix":"// before (@WebSocketClient endpoint)\n@OnMessage\nvoid onMessage(WebSocketConnection conn, String msg) { }\n// after\n@OnMessage\nvoid onMessage(WebSocketClientConnection conn, String msg) { }","handlingStrategy":"type-guard","validationCode":"// Client-side check\nif (method.getParameterTypes() contains WebSocketConnection.class)\n    throw new IllegalStateException(\"use WebSocketClientConnection in clients\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Double-check imports when copying code from server endpoints","Keep separate base classes for client and server callbacks"],"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-12T22:17:10.623Z"}