quarkusio/quarkus · error · ConfigurationException

Annotations '<annotations>' can only be used when proactive

Error message

Annotations '<annotations>' can only be used when proactive authentication is disabled and either Quarkus REST, RESTEasy Classic or WebSockets Next extension is present

What it means

Annotations like @Basic, @Form, @Mtls (auth mechanism annotations) are implemented via interceptors that only work when proactive authentication is disabled and a framework that supports per-endpoint mechanism selection (Quarkus REST, RESTEasy Classic, or WebSockets Next) is present. If either condition fails, the build fails with a ConfigurationException listing the offending annotations. This prevents silently ignored security annotations.

Source

Thrown at extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/HttpSecurityProcessor.java:760

                }
                throw new RuntimeException("""
                        Found method annotated with the @AuthorizationPolicy annotation that is not an endpoint: %s#%s
                        """.formatted(method.declaringClass().name().toString(), method.name()));
            }
            return Stream.of(method);
        }
        return target.asClass().methods().stream()
                .filter(HttpSecurityProcessor::hasProperEndpointModifiers)
                .filter(mi -> !securityTransformer.hasSecurityAnnotation(mi));
    }

    private static void validateAuthMechanismAnnotationUsage(Capabilities capabilities,
            VertxHttpBuildTimeConfig buildTimeConfig,
            DotName[] annotationNames) {
        if (buildTimeConfig.auth().proactive()
                || (capabilities.isMissing(Capability.RESTEASY_REACTIVE) && capabilities.isMissing(Capability.RESTEASY)
                        && capabilities.isMissing(Capability.WEBSOCKETS_NEXT))) {
            throw new ConfigurationException("Annotations '" + Arrays.toString(annotationNames) + "' can only be used when"
                    + " proactive authentication is disabled and either Quarkus REST, RESTEasy Classic or WebSockets Next"
                    + " extension is present");
        }
    }

    private static boolean isMtlsClientAuthenticationEnabled(VertxHttpBuildTimeConfig httpBuildTimeConfig) {
        return !ClientAuth.NONE.equals(httpBuildTimeConfig.tlsClientAuth());
    }

    public static Set<MethodInfo> collectClassMethodsWithoutRbacAnnotation(Collection<ClassInfo> classes,
            SecurityTransformer securityTransformer) {
        return classes
                .stream()
                .filter(c -> !securityTransformer.hasSecurityAnnotation(c))
                .map(ClassInfo::methods)
                .flatMap(Collection::stream)
                .filter(HttpSecurityProcessor::hasProperEndpointModifiers)
                .filter(m -> !securityTransformer.hasSecurityAnnotation(m))

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.http.auth.proactive=false in application.properties
Add one of: quarkus-rest (RESTEasy Reactive), quarkus-resteasy, or quarkus-websockets-next extension
Remove the mechanism annotations if per-endpoint auth mechanisms aren't needed

Example fix

// before (application.properties)
quarkus.http.auth.proactive=true
// after
quarkus.http.auth.proactive=false

Defensive patterns

Strategy: validation

Validate before calling

// application.properties check before build
// quarkus.http.auth.proactive=false
// and one of: quarkus-rest / quarkus-resteasy / quarkus-websockets-next dependency present

Prevention

Disable proactive auth whenever using per-endpoint mechanism annotations
Keep quarkus-rest (or resteasy-classic) in the project if you use @Basic/@Form annotations
Document that mechanism annotations require one of the supported extensions

When it happens

Trigger: Using HTTP auth mechanism annotations while quarkus.http.auth.proactive=true, or in an application lacking RESTEasy Reactive, RESTEasy Classic, and WebSockets Next extensions.

Common situations: Adding @Basic or @Form to a non-REST app (e.g. plain Vert.x or gRPC); upgrading an app where proactive auth was left enabled; forgetting to add a REST extension while using mechanism annotations.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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