quarkusio/quarkus · error · RuntimeException

The '%s' policies required by the '%s' annotation instances

Error message

The '%s' policies required by the '%s' annotation instances are missing: %s

What it means

At build/recorder time, the websockets-next server collects HttpSecurityPolicy instances required by @AuthorizationPolicy-annotated endpoints. If any required named policy is not registered as an HttpSecurityPolicy bean, the recorder throws this RuntimeException listing the missing policies and the endpoints that require them.

Source

Thrown at extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/runtime/WebSocketServerRecorder.java:262

                    endpointToPolicy = new HashMap<>();
                    Instance<HttpSecurityPolicy> policies = ctx.getInjectedReference(new TypeLiteral<>() {
                    });
                    var policyNameToEndpointsRemainder = new HashMap<>(policyNameToEndpoints);
                    for (HttpSecurityPolicy policy : policies) {
                        String policyName = policy.name();
                        if (policyName != null && policyNameToEndpoints.containsKey(policyName)) {
                            for (String endpoint : policyNameToEndpoints.get(policyName)) {
                                endpointToPolicy.put(endpoint, policy);
                            }
                            policyNameToEndpointsRemainder.remove(policyName);
                        }
                    }
                    if (!policyNameToEndpointsRemainder.isEmpty()) {
                        String missingPolicies = policyNameToEndpointsRemainder.entrySet().stream()
                                .map(e -> "policy '%s' is required by endpoints '%s'".formatted(e.getKey(), e.getValue()))
                                .collect(Collectors.joining(System.lineSeparator()));
                        throw new RuntimeException("The '%s' policies required by the '%s' annotation instances are missing: %s"
                                .formatted(HttpSecurityPolicy.class.getName(), AuthorizationPolicy.class.getName(),
                                        missingPolicies));
                    }
                }
                return new SecurityHttpUpgradeCheck(config.security().authFailureRedirectUrl().orElse(null), endpointToCheck,
                        securityEventHelper, endpointToPolicy, authorizationRequestContext);
            }
        };
    }

    public Function<SyntheticCreationalContext<HttpUpgradeSecurityInterceptor>, HttpUpgradeSecurityInterceptor> createHttpUpgradeSecurityInterceptor(
            Map<String, String> classNameToEndpointId) {
        return new Function<SyntheticCreationalContext<HttpUpgradeSecurityInterceptor>, HttpUpgradeSecurityInterceptor>() {
            @Override
            public HttpUpgradeSecurityInterceptor apply(SyntheticCreationalContext<HttpUpgradeSecurityInterceptor> ctx) {
                EagerSecurityInterceptorStorage storage = ctx.getInjectedReference(EagerSecurityInterceptorStorage.class);
                Map<String, Consumer<RoutingContext>> endpointIdToInterceptor = new HashMap<>();
                classNameToEndpointId.forEach((className, endpointId) -> {

View on GitHub (pinned to e1c734241f)

Solutions

Implement and register an HttpSecurityPolicy CDI bean with the exact required name
Verify the name in @AuthorizationPolicy matches the policy's name()
Check that the extension providing the policy (e.g. quarkus-oidc, quarkus-http-security) is a dependency
Review the error message: it lists each missing policy and its dependent endpoints

Example fix

// before
@AuthorizationPolicy(name = "admin-only") // no policy registered
// after
@Singleton
public class AdminOnlyPolicy implements HttpSecurityPolicy {
    public String name() { return "admin-only"; }
    ...
}

Defensive patterns

Strategy: validation

Validate before calling

// startup smoke: ensure every @AuthorizationPolicy name has an HttpSecurityPolicy bean
Set<String> required = Set.of("admin-only");
required.forEach(name -> {
    if (instance.list(HttpSecurityPolicy.class).stream().noneMatch(p -> name.equals(p.name())))
        throw new IllegalStateException("Missing policy: " + name);
});

Prevention

Keep @AuthorizationPolicy names and HttpSecurityPolicy.name() in one constants class
Add an ArC/startup test asserting all referenced policies resolve
Verify required security extensions are on the classpath

When it happens

Trigger: An endpoint method or class annotated with @AuthorizationPolicy(value="policy-name") (or similar instance) whose named policy has no corresponding HttpSecurityPolicy CDI bean registered — or the bean was removed/renamed.

Common situations: Renaming an HttpSecurityPolicy bean name without updating @AuthorizationPolicy; forgetting to register a custom policy class as a @Bean; removing a security extension that provided the policy.

Related errors

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