{"record":{"id":"bd700856ca49ba34","repo":"quarkusio/quarkus","slug":"method-parameter-annotated-with-pathparam-must-be","errorCode":null,"errorMessage":"Method parameter annotated with @PathParam must be java.lang.String: %s","messagePattern":"Method parameter annotated with @PathParam must be java\\.lang\\.String: (.+?)","errorType":"exception","errorClass":"WebSocketException","httpStatus":null,"severity":"error","filePath":"extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/PathParamCallbackArgument.java","lineNumber":24,"sourceCode":"\nimport org.jboss.jandex.AnnotationInstance;\nimport org.jboss.jandex.AnnotationValue;\n\nimport 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    }","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/PathParamCallbackArgument.java#L6-L42","documentation":"Parameters annotated with @PathParam in websockets-next callback methods must be of type java.lang.String. If any other type is used, the build fails with WebSocketException naming the offending method. This restriction keeps path parameter extraction simple and type-safe.","triggerScenarios":"Annotating a callback parameter with @PathParam where the declared type is not String (e.g. Integer, Long, UUID, primitives).","commonSituations":"Assuming automatic conversion like JAX-RS @PathParam; converting REST-style endpoint code to websockets-next endpoints; using numeric IDs typed as long/Integer.","solutions":["Change the parameter type to String and parse manually inside the method","Keep numeric IDs as String in the endpoint path template and convert after injection","Check the migration guide if porting from classic websockets/JAX-RS where conversion existed"],"exampleFix":"// before\n@OnMessage\nvoid onMessage(@PathParam(\"id\") Long id, String msg) { }\n// after\n@OnMessage\nvoid onMessage(@PathParam(\"id\") String id, String msg) {\n  Long parsed = Long.valueOf(id);\n}","handlingStrategy":"validation","validationCode":"for (Parameter p : callbackMethod.getParameters())\n    if (p.isAnnotationPresent(PathParam.class) && p.getType() != String.class)\n        throw new IllegalArgumentException(\"@PathParam must be String: \" + p);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember websockets-next does not auto-convert path params","Always declare @PathParam params as String and parse explicitly","Review ported code from JAX-RS for this assumption"],"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"}