quarkusio/quarkus · error · IllegalStateException

A failure handler may only define one failure parameter - ro

Error message

A failure handler may only define one failure parameter - route method %s declared on %s

What it means

Raised by ReactiveRoutesProcessor.validateRouteMethod when a route method annotated as a FAILURE handler declares more than one Throwable parameter. Failure routes receive exactly one failure argument; the validation counts isThrowable parameters and the count exceeding one makes the generated failure handler signature ambiguous, so the build aborts with the method and bean names.

Source

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

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

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

            if (method.returnType().kind() == Kind.VOID && !canEndResponse) {
                throw new IllegalStateException(String.format(
                        "Route method that returns void must accept at least one parameter that can end the response [method: %s, bean: %s]",
                        method, bean));
            }

            if (failureParams > 1) {
                throw new IllegalStateException(String.format(
                        "A failure handler may only define one failure parameter - route method %s declared on %s",
                        method, bean));
            }
        }
    }

    private String generateHandler(HandlerDescriptor desc, BeanInfo bean, MethodInfo method, Gizmo gizmo,
            TransformedAnnotationsBuildItem transformedAnnotations, AnnotationInstance routeAnnotation,
            BuildProducer<ReflectiveHierarchyBuildItem> reflectiveHierarchy, String defaultProduces,
            boolean validatorAvailable, IndexView index) {

        if (desc.requireValidation() && !validatorAvailable) {
            throw new IllegalStateException(
                    "A route requires validation, but the Hibernate Validator extension is not present");
        }

        StringBuilder signature = new StringBuilder();
        signature.append(method.name()).append("_").append(method.returnType().name());

View on GitHub (pinned to e1c734241f)

Solutions

1. Keep a single Throwable parameter on the failure route method
2. Split handling of different exception types into separate failure route methods

When it happens

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