{"record":{"id":"0cfae737e92beab3","repo":"quarkusio/quarkus","slug":"route-filter-method-must-accept-exactly-one-parame","errorCode":null,"errorMessage":"Route filter method must accept exactly one parameter of type %s: %s [method: %s, bean: %s]","messagePattern":"Route filter method must accept exactly one parameter of type (.+?): (.+?) \\[method: (.+?), bean: (.+?)\\]","errorType":"exception","errorClass":"java.lang.IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java","lineNumber":524,"sourceCode":"    @BuildStep\n    AutoAddScopeBuildItem autoAddScope() {\n        return AutoAddScopeBuildItem.builder()\n                .containsAnnotations(DotNames.ROUTE,\n                        DotNames.ROUTES,\n                        DotNames.ROUTE_FILTER)\n                .defaultScope(BuiltinScope.SINGLETON)\n                .reason(\"Found route handler business methods\").build();\n    }\n\n    private void validateRouteFilterMethod(BeanInfo bean, MethodInfo method) {\n        if (!method.returnType().kind().equals(Type.Kind.VOID)) {\n            throw new IllegalStateException(\n                    String.format(\"Route filter method must return void [method: %s, bean: %s]\", method, bean));\n        }\n        List<Type> params = method.parameterTypes();\n        if (params.size() != 1 || !params.get(0).name()\n                .equals(DotNames.ROUTING_CONTEXT)) {\n            throw new IllegalStateException(String.format(\n                    \"Route filter method must accept exactly one parameter of type %s: %s [method: %s, bean: %s]\",\n                    DotNames.ROUTING_CONTEXT, params, method, bean));\n        }\n    }\n\n    private void validateRouteMethod(BeanInfo bean, MethodInfo method,\n            TransformedAnnotationsBuildItem transformedAnnotations, IndexView index, AnnotationInstance routeAnnotation) {\n        List<Type> params = method.parameterTypes();\n        if (params.isEmpty()) {\n            if (method.returnType().kind() == Kind.VOID && params.isEmpty()) {\n                throw new IllegalStateException(String.format(\n                        \"Route method that returns void must accept at least one injectable parameter [method: %s, bean: %s]\",\n                        method, bean));\n            }\n        } else {\n            AnnotationValue typeValue = routeAnnotation.value(VALUE_TYPE);\n            Route.HandlerType handlerType = typeValue == null\n                    ? Route.HandlerType.NORMAL","sourceCodeStart":506,"sourceCodeEnd":542,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java#L506-L542","documentation":"A @RouteFilter method must accept exactly one parameter of type io.vertx.ext.web.RoutingContext. validateRouteFilterMethod throws IllegalStateException when the parameter list is empty, has multiple parameters, or the single parameter is not RoutingContext.","triggerScenarios":"@RouteFilter method with zero parameters, with two or more parameters, or with a single parameter of a different type (e.g. HttpServerRequest, custom context).","commonSituations":"Injecting beans as filter parameters out of habit from other frameworks; adding extra context args when extending a filter; confusing route filter signature with route handler method signature.","solutions":["Declare exactly one parameter of type io.vertx.ext.web.RoutingContext","Obtain other dependencies via constructor/field CDI injection instead of method parameters","Align the signature with an existing working @RouteFilter example in the project"],"exampleFix":"// before\n@RouteFilter(100)\npublic void filter(RoutingContext rc, MyService svc) { ... }\n// after\n@RouteFilter(100)\npublic void filter(RoutingContext rc) { rc.next(); }\n\nprivate final MyService svc; // injected via constructor","handlingStrategy":"validation","validationCode":"Parameter[] ps = m.getParameters();\nif (m.isAnnotationPresent(RouteFilter.class)\n        && (ps.length != 1 || ps[0].getType() != RoutingContext.class)) {\n    throw new IllegalStateException(\"@RouteFilter takes exactly one RoutingContext\");\n}","typeGuard":"boolean isValidRouteFilter(Method m) {\n    return m.getReturnType() == void.class\n        && m.getParameterCount() == 1\n        && m.getParameterTypes()[0] == RoutingContext.class;\n}","tryCatchPattern":null,"preventionTips":["Use exactly one RoutingContext parameter in @RouteFilter methods","Inject dependencies via CDI constructor/field injection instead of parameters","Don't confuse route filter signatures with route handler signatures"],"tags":["quarkus","reactive-routes","route-filter","build-time"],"backgroundTag":"invalid-route-filter-signature","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}