{"record":{"id":"2ea7800f400422ff","repo":"quarkusio/quarkus","slug":"global-error-handlers-may-not-accept-pathparam-pa","errorCode":null,"errorMessage":"Global error handlers may not accept @PathParam parameters: %s","messagePattern":"Global error handlers may not accept @PathParam parameters: (.+?)","errorType":"exception","errorClass":"WebSocketException","httpStatus":null,"severity":"error","filePath":"extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/PathParamCallbackArgument.java","lineNumber":28,"sourceCode":"import io.quarkus.arc.processor.Annotations;\nimport io.quarkus.gizmo2.Const;\nimport io.quarkus.gizmo2.Expr;\nimport io.quarkus.gizmo2.desc.MethodDesc;\nimport io.quarkus.websockets.next.WebSocketException;\nimport io.quarkus.websockets.next.runtime.WebSocketConnectionBase;\n\nclass PathParamCallbackArgument implements CallbackArgument {\n\n    @Override\n    public boolean matches(ParameterContext context) {\n        String name = getParamName(context);\n        if (name != null) {\n            if (!context.parameter().type().name().equals(WebSocketDotNames.STRING)) {\n                throw new WebSocketException(\"Method parameter annotated with @PathParam must be java.lang.String: \"\n                        + WebSocketProcessor.methodToString(context.parameter().method()));\n            }\n            if (context.endpointPath() == null) {\n                throw new WebSocketException(\"Global error handlers may not accept @PathParam parameters: \"\n                        + WebSocketProcessor.methodToString(context.parameter().method()));\n            }\n            List<String> pathParams = getPathParamNames(context.endpointPath());\n            if (!pathParams.contains(name)) {\n                throw new WebSocketException(\n                        String.format(\n                                \"@PathParam name [%s] must be used in the endpoint path [%s]: %s\", name,\n                                context.endpointPath(),\n                                WebSocketProcessor.methodToString(context.parameter().method())));\n            }\n            return true;\n        }\n        return false;\n    }\n\n    @Override\n    public Expr get(InvocationBytecodeContext context) {\n        String paramName = getParamName(context);","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/PathParamCallbackArgument.java#L10-L46","documentation":"Global error handlers (declared with WebSocketGlobalErrorHandling / global @OnError) are not bound to an endpoint path, so @PathParam parameters cannot be resolved there. If a global error handler declares a @PathParam parameter, the build fails with WebSocketException. Path parameters are only meaningful for callbacks attached to an endpoint with a path template.","triggerScenarios":"Declaring @PathParam on a parameter of a global @OnError handler method (one registered globally rather than inside a specific @WebSocket endpoint).","commonSituations":"Copy-pasting an endpoint-level @OnError method into a global error handler class; wanting the path value in a global handler without realizing it is unavailable.","solutions":["Remove the @PathParam parameter from the global error handler","Move the error-handling method into the specific @WebSocket endpoint where the path param exists","Access connection-level information via WebSocketConnection parameters instead of path params"],"exampleFix":"// before (global handler)\n@OnError\nvoid onError(WebSocketConnection conn, @PathParam(\"id\") String id, Throwable t) { }\n// after\n@OnError\nvoid onError(WebSocketConnection conn, Throwable t) { }","handlingStrategy":"validation","validationCode":"// Global error handlers: assert no @PathParam parameters exist\nboolean hasPathParam = Arrays.stream(handler.getParameters())\n    .anyMatch(p -> p.isAnnotationPresent(PathParam.class));","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep global handlers free of endpoint-specific parameters","Move handlers needing @PathParam into the specific endpoint","Use WebSocketConnection for generic context in global handlers"],"tags":["quarkus","websockets-next","build-time","path-params"],"backgroundTag":"websocket-pathparam-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"}