{"record":{"id":"598d62d830b838c9","repo":"quarkusio/quarkus","slug":"pathparam-name-s-must-be-used-in-the-endpoint","errorCode":null,"errorMessage":"@PathParam name [%s] must be used in the endpoint path [%s]: %s","messagePattern":"@PathParam name \\[(.+?)\\] must be used in the endpoint path \\[(.+?)\\]: (.+?)","errorType":"exception","errorClass":"WebSocketException","httpStatus":null,"severity":"error","filePath":"extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/PathParamCallbackArgument.java","lineNumber":33,"sourceCode":"import 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);\n        return context.bytecode().invokeVirtual(\n                MethodDesc.of(WebSocketConnectionBase.class, \"pathParam\", String.class, String.class),\n                context.getConnection(), Const.of(paramName));\n    }\n","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/PathParamCallbackArgument.java#L15-L51","documentation":"Quarkus websockets-next throws this during build-time validation when a callback method parameter annotated with @PathParam declares a name that does not appear as a path segment variable in the endpoint's @WebSocket/@WebSocketClient path. The path parameter would never be populated, so the deployment is rejected early. It only applies to endpoints with a path; global error handlers with @PathParam are rejected separately.","triggerScenarios":"Annotating a callback parameter with @PathParam(\"id\") (or bare @PathParam relying on -parameters names) on @OnOpen/@OnTextMessage/@OnMessage/@OnError methods while the endpoint path, e.g. @WebSocket(path=\"/ws/{endpoint}\"), contains no matching {id} segment.","commonSituations":"Renaming a path variable in the endpoint path without updating the @PathParam value; copying a handler from another endpoint with different path variables; typos like {userId} vs @PathParam(\"user\"); adding @PathParam to a global error handler whose endpointPath is null.","solutions":["Make the @PathParam value exactly match a {name} segment in the endpoint path","Or remove the segment rename mismatch: change the path (e.g. @WebSocket(path=\"/chat/{roomId}\")) so it contains the parameter name","Or remove the @PathParam parameter if it is not needed","Verify the class is compiled with -parameters if relying on parameter names instead of explicit values"],"exampleFix":"// before\n@WebSocket(path = \"/ws/chat\")\n@OnOpen void open(@PathParam String roomId) {}\n// after\n@WebSocket(path = \"/ws/chat/{roomId}\")\n@OnOpen void open(@PathParam String roomId) {}","handlingStrategy":"validation","validationCode":"// Before building, assert every @PathParam name appears in the path template\nstatic void checkPathParams(String path, String... pathParamNames) {\n  for (String p : pathParamNames) {\n    if (!path.contains(\"{\" + p + \"}\"))\n      throw new IllegalStateException(\"@PathParam '\" + p + \"' missing from path \" + path);\n  }\n}\n// checkPathParams(\"/ws/chat/{roomId}\", \"roomId\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always mirror path variable names exactly between the path template and @PathParam values","Use explicit @PathParam(\"name\") values rather than relying on bare annotations","Review copied handler code for stale path parameter names"],"tags":["websocket","build-time","path-parameter","quarkus"],"backgroundTag":"path-parameter-name-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"}