quarkusio/quarkus · error · IllegalStateException

HandlerType.%s is not legal for parameter %s of route method

Error message

HandlerType.%s is not legal for parameter %s of route method %s declared on %s

What it means

Raised by ReactiveRoutesProcessor.validateRouteMethod when the ParameterInjector selected for a parameter declares a target handler type that does not match the method's configured Route.HandlerType (e.g. a failure-only injector used in a NORMAL route). The injector advertises which handler types it is legal for; the validation compares that with the handlerType derived from the @Route annotation and fails fast at build time with the offending injector, parameter index, method and bean.

Source

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

            int idx = 0;
            int failureParams = 0;
            for (Type paramType : params) {
                Set<AnnotationInstance> paramAnnotations = Annotations.getParameterAnnotations(transformedAnnotations,
                        method, idx);
                List<ParameterInjector> injectors = getMatchingInjectors(paramType, paramAnnotations, index);
                if (injectors.isEmpty()) {
                    throw new IllegalStateException(String.format(
                            "No parameter injector found for parameter %s of route method %s declared on %s", idx,
                            method, bean));
                }
                if (injectors.size() > 1) {
                    throw new IllegalStateException(String.format(
                            "Multiple parameter injectors found for parameter %s of route method %s declared on %s",
                            idx, method, bean));
                }
                ParameterInjector injector = injectors.get(0);
                if (injector.getTargetHandlerType() != null && !injector.getTargetHandlerType().equals(handlerType)) {
                    throw new IllegalStateException(String.format(
                            "HandlerType.%s is not legal for parameter %s of route method %s declared on %s",
                            injector.getTargetHandlerType(), idx, method, bean));
                }

                // A param injector may validate the parameter annotations
                injector.validate(bean, method, routeAnnotation, paramType, paramAnnotations);

                if (injector.canEndResponse) {
                    canEndResponse = true;
                }

                if (Route.HandlerType.FAILURE == handlerType && isThrowable(paramType, index)) {
                    failureParams++;
                }
                idx++;
            }

            if (method.returnType().kind() == Kind.VOID && !canEndResponse) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Align the @Route handlerType with the parameter (e.g. use a failure parameter only on a FAILURE route)
2. Remove the parameter type that requires a different handler type from this method
3. If using a custom ParameterInjector, fix its target handler type declaration

When it happens

Trigger: Thrown at extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java:574 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/3da29396c5c0ebcc. Report an issue: GitHub.