{"record":{"id":"fc565bfce29e8792","repo":"quarkusio/quarkus","slug":"a-path-param-name-must-only-contain-word-character","errorCode":null,"errorMessage":"A path param name must only contain word characters (a-zA-Z_0-9): %s [route method %s declared on %s]","messagePattern":"A path param name must only contain word characters \\(a-zA-Z_0-9\\): (.+?) \\[route method (.+?) declared on (.+?)\\]","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java","lineNumber":1348,"sourceCode":"                .requireAnnotations(DotNames.PARAM)\n                .valueProvider(new ParamAndHeaderProvider(DotNames.PARAM, Methods.REQUEST_PARAMS, Methods.REQUEST_GET_PARAM))\n                .validate(new ParamValidator() {\n                    @Override\n                    public void validate(BeanInfo bean, MethodInfo method, AnnotationInstance routeAnnotation, Type paramType,\n                            Set<AnnotationInstance> paramAnnotations) {\n                        AnnotationInstance paramAnnotation = Annotations.find(paramAnnotations, DotNames.PARAM);\n                        AnnotationValue paramNameValue = paramAnnotation.value();\n                        if (paramNameValue != null && !paramNameValue.asString().equals(Param.ELEMENT_NAME)) {\n                            String paramName = paramNameValue.asString();\n                            AnnotationValue regexValue = routeAnnotation.value(VALUE_REGEX);\n                            AnnotationValue pathValue = routeAnnotation.value(VALUE_PATH);\n                            if (regexValue == null && pathValue != null) {\n                                String path = pathValue.asString();\n                                // Validate the name if used as a path parameter\n                                if (path.contains(\":\" + paramName) && !PATH_PARAM_PATTERN.matcher(paramName).matches()) {\n                                    // TODO This requirement should be relaxed in vertx 4.0.3+\n                                    // https://github.com/vert-x3/vertx-web/pull/1881\n                                    throw new IllegalStateException(String.format(\n                                            \"A path param name must only contain word characters (a-zA-Z_0-9): %s [route method %s declared on %s]\",\n                                            paramName, method, bean.getBeanClass()));\n                                }\n                            }\n                        }\n                    }\n                })\n                .build());\n\n        injectors.add(ParameterInjector.builder()\n                .matchPrimitiveWrappers()\n                .matchType(DotName.STRING_NAME)\n                .matchOptionalOf(DotName.STRING_NAME)\n                .matchListOf(DotName.STRING_NAME)\n                .requireAnnotations(DotNames.HEADER)\n                .valueProvider(new ParamAndHeaderProvider(DotNames.HEADER, Methods.REQUEST_HEADERS, Methods.REQUEST_GET_HEADER))\n                .build());\n","sourceCodeStart":1330,"sourceCodeEnd":1366,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java#L1330-L1366","documentation":"Raised by the ParamValidator inside ReactiveRoutesProcessor when a @Param path-parameter name extracted from the route method's annotations (or the parameter name itself) contains characters outside a-zA-Z_0-9. Path parameter names must match the word-character tokens the URI template parser generates, so a name with spaces, dashes or digits-with-symbols cannot be bound to a route path segment, and the build-time validator rejects it with the offending name, method and bean.","triggerScenarios":"Thrown at extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java:1348 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Rename the @Param path parameter so it uses only word characters (a-zA-Z_0-9), e.g. change {user-id} to {userId} in the route path and update the @Param value to match.","Remove any hyphens, dots, or other special characters from the path template segment for this parameter.","If the URL segment must contain non-word characters, capture it differently, e.g. use a regex-free path variable with a normalized name and handle encoding, or match via a custom route outside reactive-routes annotations.","Rebuild/restart the application after fixing the path and verify the route is registered without build-time failure."],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}