{"record":{"id":"26d75f22b01e221e","repo":"quarkusio/quarkus","slug":"a-failure-handler-may-only-define-one-failure-para","errorCode":null,"errorMessage":"A failure handler may only define one failure parameter - route method %s declared on %s","messagePattern":"A failure handler may only define one failure parameter - 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":599,"sourceCode":"\n                if (injector.canEndResponse) {\n                    canEndResponse = true;\n                }\n\n                if (Route.HandlerType.FAILURE == handlerType && isThrowable(paramType, index)) {\n                    failureParams++;\n                }\n                idx++;\n            }\n\n            if (method.returnType().kind() == Kind.VOID && !canEndResponse) {\n                throw new IllegalStateException(String.format(\n                        \"Route method that returns void must accept at least one parameter that can end the response [method: %s, bean: %s]\",\n                        method, bean));\n            }\n\n            if (failureParams > 1) {\n                throw new IllegalStateException(String.format(\n                        \"A failure handler may only define one failure parameter - route method %s declared on %s\",\n                        method, bean));\n            }\n        }\n    }\n\n    private String generateHandler(HandlerDescriptor desc, BeanInfo bean, MethodInfo method, Gizmo gizmo,\n            TransformedAnnotationsBuildItem transformedAnnotations, AnnotationInstance routeAnnotation,\n            BuildProducer<ReflectiveHierarchyBuildItem> reflectiveHierarchy, String defaultProduces,\n            boolean validatorAvailable, IndexView index) {\n\n        if (desc.requireValidation() && !validatorAvailable) {\n            throw new IllegalStateException(\n                    \"A route requires validation, but the Hibernate Validator extension is not present\");\n        }\n\n        StringBuilder signature = new StringBuilder();\n        signature.append(method.name()).append(\"_\").append(method.returnType().name());","sourceCodeStart":581,"sourceCodeEnd":617,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java#L581-L617","documentation":"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.","triggerScenarios":"Thrown at extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java:599 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Keep a single Throwable parameter on the failure route method","Split handling of different exception types into separate failure route methods"],"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-14T00:17:10.932Z"}