quarkusio/quarkus · error · RuntimeException

The @AuthorizationPolicy annotation placed on '<target>' mus

Error message

The @AuthorizationPolicy annotation placed on '<target>' must not have blank policy name.

What it means

During HTTP security processing, Quarkus scans all @AuthorizationPolicy annotations and reads their 'name' attribute, which identifies the registered policy to apply. The annotation is useless without a name because no policy can be looked up, so the build fails fast with a RuntimeException naming the annotated class or method. This guards against typos or placeholder values like "" left in the annotation.

Source

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

                    new AdditionalSecurityConstrainerEventPropsBuildItem(recorder.createAdditionalSecEventPropsSupplier()));
        }
    }

    private static Map<MethodInfo, String> gatherAuthorizationPolicyInstances(CombinedIndexBuildItem combinedIndex,
            Optional<SecurityTransformerBuildItem> securityTransformerBuildItem) {
        SecurityTransformer securityTransformer = SecurityTransformerBuildItem.createSecurityTransformer(
                combinedIndex.getIndex(), securityTransformerBuildItem);
        var methodToPolicy = securityTransformer
                // @AuthorizationPolicy(name = "policy-name")
                .getAnnotations(AUTHORIZATION_POLICY)
                .stream()
                .flatMap(ai -> {
                    var policyName = ai.value("name").asString();
                    if (policyName.isBlank()) {
                        var targetName = ai.target().kind() == AnnotationTarget.Kind.CLASS
                                ? ai.target().asClass().name().toString()
                                : ai.target().asMethod().name();
                        throw new RuntimeException("""
                                The @AuthorizationPolicy annotation placed on '%s' must not have blank policy name.
                                """.formatted(targetName));
                    }
                    return getPolicyTargetEndpointCandidates(ai.target(), securityTransformer)
                            .map(mi -> Map.entry(mi, policyName));
                })
                .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
        return Collections.unmodifiableMap(methodToPolicy);
    }

    @BuildStep
    AdditionalSecurityAnnotationBuildItem registerAuthorizationPolicyAnnotation() {
        return new AdditionalSecurityAnnotationBuildItem(AUTHORIZATION_POLICY);
    }

    /**
     * Implements {@link io.quarkus.vertx.http.runtime.security.AuthorizationPolicyStorage} as a bean.
     * If no {@link AuthorizationPolicy} are detected, generated bean will look like this:

View on GitHub (pinned to e1c734241f)

Solutions

1. Set a non-blank policy name in the annotation, e.g. @AuthorizationPolicy(name = "admin")
2. Ensure a policy with that name is registered (e.g. via a PolicyMappingBuildItem or named HttpSecurityPolicy)
3. Rebuild the application after fixing the annotation

Example fix

// before
@AuthorizationPolicy(name = "")
public class AdminResource { ... }
// after
@AuthorizationPolicy(name = "admin-policy")
public class AdminResource { ... }

AuthorizationPolicy policy = resource.getClass().getAnnotation(AuthorizationPolicy.class);
if (policy != null && (policy.name() == null || policy.name().isBlank())) {
    throw new IllegalStateException("@AuthorizationPolicy on " + resource.getClass().getName() + " needs a non-blank name");
}

boolean hasNamedPolicy(Class<?> c) {
    AuthorizationPolicy a = c.getAnnotation(AuthorizationPolicy.class);
    return a != null && !a.name().isBlank();
}

When it happens

Trigger: Annotating a REST endpoint class or method with @AuthorizationPolicy(name = "") or @AuthorizationPolicy (leaving name blank/default) while the vertx-http security processing runs at build time.

Common situations: Copying an @AuthorizationPolicy example and forgetting to fill in the policy name; defining the policy later and leaving a placeholder empty string; refactoring that removed the name value.

Related errors

• @PermissionChecker annotation placed on the '%s' attribute '
• Only one of the '<annotations>' annotations can be applied o
• Security annotations '<annotations>' cannot be applied on th
• Only one of the '<annotations>' annotations can be applied o
• The configuration ${clazz} is missing the @ConfigRoot annota

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