quarkusio/quarkus · error · java.lang.IllegalStateException

Route filter method must accept exactly one parameter of typ

Error message

Route filter method must accept exactly one parameter of type %s: %s [method: %s, bean: %s]

What it means

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.

Source

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

    @BuildStep
    AutoAddScopeBuildItem autoAddScope() {
        return AutoAddScopeBuildItem.builder()
                .containsAnnotations(DotNames.ROUTE,
                        DotNames.ROUTES,
                        DotNames.ROUTE_FILTER)
                .defaultScope(BuiltinScope.SINGLETON)
                .reason("Found route handler business methods").build();
    }

    private void validateRouteFilterMethod(BeanInfo bean, MethodInfo method) {
        if (!method.returnType().kind().equals(Type.Kind.VOID)) {
            throw new IllegalStateException(
                    String.format("Route filter method must return void [method: %s, bean: %s]", method, bean));
        }
        List<Type> params = method.parameterTypes();
        if (params.size() != 1 || !params.get(0).name()
                .equals(DotNames.ROUTING_CONTEXT)) {
            throw new IllegalStateException(String.format(
                    "Route filter method must accept exactly one parameter of type %s: %s [method: %s, bean: %s]",
                    DotNames.ROUTING_CONTEXT, params, method, bean));
        }
    }

    private void validateRouteMethod(BeanInfo bean, MethodInfo method,
            TransformedAnnotationsBuildItem transformedAnnotations, IndexView index, AnnotationInstance routeAnnotation) {
        List<Type> params = method.parameterTypes();
        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

View on GitHub (pinned to e1c734241f)

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

Example fix

// before
@RouteFilter(100)
public void filter(RoutingContext rc, MyService svc) { ... }
// after
@RouteFilter(100)
public void filter(RoutingContext rc) { rc.next(); }

private final MyService svc; // injected via constructor

Defensive patterns

Strategy: validation

Validate before calling

Parameter[] ps = m.getParameters();
if (m.isAnnotationPresent(RouteFilter.class)
        && (ps.length != 1 || ps[0].getType() != RoutingContext.class)) {
    throw new IllegalStateException("@RouteFilter takes exactly one RoutingContext");
}

Type guard

boolean isValidRouteFilter(Method m) {
    return m.getReturnType() == void.class
        && m.getParameterCount() == 1
        && m.getParameterTypes()[0] == RoutingContext.class;
}

Prevention

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

When it happens

Trigger: @RouteFilter method with zero parameters, with two or more parameters, or with a single parameter of a different type (e.g. HttpServerRequest, custom context).

Common situations: 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.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/0cfae737e92beab3. Report an issue: GitHub.