quarkusio/quarkus · error · RuntimeException

The combination of '@${annotationName}' and '@ServerRequestF

Error message

The combination of '@${annotationName}' and '@ServerRequestFilter' or '@ServerResponseFilter' is not allowed. Offending method is '${methodName}' of class '${className}'

What it means

Quarkus REST rejects combining bean-conditional annotations (@IfBuildProfile, @IfBuildProperty, @Startup, etc. — CONDITIONAL_BEAN_ANNOTATIONS) with @ServerRequestFilter or @ServerResponseFilter. During deployment, custom-annotated filter methods are generated into beans, and the conditional annotation would be lost or ambiguous, so the build fails fast.

Source

Thrown at extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/ResteasyReactiveScanningProcessor.java:437

                indexer.add(filter.getClassName());
            }
            for (CustomContainerResponseFilterBuildItem filter : customContainerResponseFilters) {
                indexer.add(filter.getClassName());
            }
            for (CustomExceptionMapperBuildItem mapper : customExceptionMappers) {
                indexer.add(mapper.getClassName());
            }
            LazyIndexer.Result result = indexer.complete();
            index = CompositeIndex.create(index, result.index());
        }

        List<FilterGeneration.GeneratedFilter> generatedFilters = FilterGeneration.generate(index,
                Set.of(HTTP_SERVER_REQUEST, HTTP_SERVER_RESPONSE, ROUTING_CONTEXT), Set.of(Unremovable.class.getName()),
                (methodInfo -> {
                    List<AnnotationInstance> methodAnnotations = methodInfo.annotations();
                    for (AnnotationInstance methodAnnotation : methodAnnotations) {
                        if (CONDITIONAL_BEAN_ANNOTATIONS.contains(methodAnnotation.name())) {
                            throw new RuntimeException("The combination of '@" + methodAnnotation.name().withoutPackagePrefix()
                                    + "' and '@ServerRequestFilter' or '@ServerResponseFilter' is not allowed. Offending method is '"
                                    + methodInfo.name() + "' of class '" + methodInfo.declaringClass().name() + "'");
                        }
                    }

                    List<AnnotationInstance> classAnnotations = methodInfo.declaringClass().declaredAnnotations();
                    for (AnnotationInstance classAnnotation : classAnnotations) {
                        if (CONDITIONAL_BEAN_ANNOTATIONS.contains(classAnnotation.name())) {
                            return true;
                        }
                    }
                    return false;
                }));
        for (var generated : generatedFilters) {
            for (var i : generated.getGeneratedClasses()) {
                generatedBean.produce(new GeneratedBeanBuildItem(i.getName(), i.getData()));
            }
            if (generated.isRequestFilter()) {

View on GitHub (pinned to e1c734241f)

Solutions

Remove the conditional annotation from the filter method
Move the conditional annotation to the declaring class level (so the whole bean is conditional)
Implement the filter as a regular CDI bean with ContainerRequestFilter/ContainerResponseFilter and apply the conditional annotation there
Split the filter into per-profile classes each with its own @ServerRequestFilter implementation

Example fix

// before
@IfBuildProfile("prod")
@ServerRequestFilter
public void filter(HttpServerRequest req) { ... }
// after: annotate the class instead
@IfBuildProfile("prod")
public class ProdFilters {
    @ServerRequestFilter
    public void filter(HttpServerRequest req) { ... }
}

Defensive patterns

Strategy: validation

Validate before calling

// build-time check: no conditional annotations on filter methods
for (AnnotationInstance a : method.annotations()) {
    if (CONDITIONAL_BEAN_ANNOTATIONS.contains(a.name())) {
        throw new IllegalArgumentException("Remove " + a + " from @ServerRequestFilter method " + method.name());
    }
}

Prevention

Never put @IfBuildProfile/@IfBuildProperty/@Startup on @ServerRequestFilter/@ServerResponseFilter methods
Apply conditions at the class level or via plain CDI filters
Review filter classes after migrating from CDI filters

When it happens

Trigger: Declaring a method annotated with @ServerRequestFilter or @ServerResponseFilter that also carries one of the conditional bean annotations (e.g. @io.quarkus.arc.profile.IfBuildProfile, @io.quarkus.arc.properties.IfBuildProperty) on the method itself.

Common situations: Trying to enable a filter only in a certain profile or property by annotating the filter method; migrating a CDI filter class to Quarkus REST's generated-filter mechanism while keeping profile annotations.

Related errors

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