quarkusio/quarkus · error · java.lang.IllegalStateException

Route business method returning a Uni/Multi/CompletionStage

Error message

Route business method returning a Uni/Multi/CompletionStage must declare a type argument on the return type [method: %s, bean: %s]

What it means

Raised by ReactiveRoutesProcessor.validateRouteMethod when a route method's declared return type is a raw Uni, Multi or CompletionStage. The processor needs the generic type argument to pick the response serializer and to generate the handler bytecode; a raw type (Kind.CLASS with no type arguments) leaves the element type unknown, so validation aborts at build time with the offending method and bean names.

Source

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

        if (params.isEmpty()) {
            if (method.returnType().kind() == Kind.VOID && params.isEmpty()) {
                throw new IllegalStateException(String.format(
                        "Route method that returns void must accept at least one injectable parameter [method: %s, bean: %s]",
                        method, bean));
            }
        } else {
            AnnotationValue typeValue = routeAnnotation.value(VALUE_TYPE);
            Route.HandlerType handlerType = typeValue == null
                    ? Route.HandlerType.NORMAL
                    : Route.HandlerType.from(typeValue.asEnum());

            DotName returnTypeName = method.returnType().name();

            if ((returnTypeName.equals(DotNames.UNI)
                    || returnTypeName.equals(DotNames.MULTI)
                    || returnTypeName.equals(DotNames.COMPLETION_STAGE))
                    && method.returnType().kind() == Kind.CLASS) {
                throw new IllegalStateException(String.format(
                        "Route business method returning a Uni/Multi/CompletionStage must declare a type argument on the return type [method: %s, bean: %s]",
                        method, bean));
            }
            boolean canEndResponse = false;
            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",

View on GitHub (pinned to e1c734241f)

Solutions

1. Declare the type argument, e.g. Uni<String> or Multi<MyItem> instead of a raw Uni
2. Check that the returned type is not erased by generics misuse or an intermediary raw type
3. Use a concrete payload type that has an available response body writer

When it happens

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