quarkusio/quarkus · error · IllegalStateException

A path param name must only contain word characters (a-zA-Z_

Error message

A path param name must only contain word characters (a-zA-Z_0-9): %s [route method %s declared on %s]

What it means

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.

Source

Thrown at extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java:1348

                .requireAnnotations(DotNames.PARAM)
                .valueProvider(new ParamAndHeaderProvider(DotNames.PARAM, Methods.REQUEST_PARAMS, Methods.REQUEST_GET_PARAM))
                .validate(new ParamValidator() {
                    @Override
                    public void validate(BeanInfo bean, MethodInfo method, AnnotationInstance routeAnnotation, Type paramType,
                            Set<AnnotationInstance> paramAnnotations) {
                        AnnotationInstance paramAnnotation = Annotations.find(paramAnnotations, DotNames.PARAM);
                        AnnotationValue paramNameValue = paramAnnotation.value();
                        if (paramNameValue != null && !paramNameValue.asString().equals(Param.ELEMENT_NAME)) {
                            String paramName = paramNameValue.asString();
                            AnnotationValue regexValue = routeAnnotation.value(VALUE_REGEX);
                            AnnotationValue pathValue = routeAnnotation.value(VALUE_PATH);
                            if (regexValue == null && pathValue != null) {
                                String path = pathValue.asString();
                                // Validate the name if used as a path parameter
                                if (path.contains(":" + paramName) && !PATH_PARAM_PATTERN.matcher(paramName).matches()) {
                                    // TODO This requirement should be relaxed in vertx 4.0.3+
                                    // https://github.com/vert-x3/vertx-web/pull/1881
                                    throw new IllegalStateException(String.format(
                                            "A path param name must only contain word characters (a-zA-Z_0-9): %s [route method %s declared on %s]",
                                            paramName, method, bean.getBeanClass()));
                                }
                            }
                        }
                    }
                })
                .build());

        injectors.add(ParameterInjector.builder()
                .matchPrimitiveWrappers()
                .matchType(DotName.STRING_NAME)
                .matchOptionalOf(DotName.STRING_NAME)
                .matchListOf(DotName.STRING_NAME)
                .requireAnnotations(DotNames.HEADER)
                .valueProvider(new ParamAndHeaderProvider(DotNames.HEADER, Methods.REQUEST_HEADERS, Methods.REQUEST_GET_HEADER))
                .build());

View on GitHub (pinned to e1c734241f)

Solutions

1. 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.
2. Remove any hyphens, dots, or other special characters from the path template segment for this parameter.
3. 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.
4. Rebuild/restart the application after fixing the path and verify the route is registered without build-time failure.

When it happens

Trigger: Thrown at extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java:1348 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/fc565bfce29e8792. Report an issue: GitHub.