quarkusio/quarkus · error · IllegalStateException

Found unknown security annotation: %s

Error message

Found unknown security annotation: %s

What it means

SecurityProcessor dispatches on the name of the security annotation found on a method/class (RolesAllowed, PermissionsAllowed, DenyAll, Authenticated, PermissionsAllowed etc.). If an annotation in the security annotation index is not one of the recognized names, the build aborts. This usually indicates a custom or unrecognized annotation that Quarkus's annotation scanner associated with security handling.

Source

Thrown at extensions/security/deployment/src/main/java/io/quarkus/security/deployment/SecurityProcessor.java:1184

                    .sorted(Comparator.comparing(item -> item.getClassName().toString())).forEach(item -> {
                        var securityAnnotationName = item.getSecurityAnnotationInstance().name();

                        final SecurityCheck securityCheck;
                        if (DENY_ALL.equals(securityAnnotationName)) {
                            securityCheck = recorder.denyAll();
                        } else if (PERMIT_ALL.equals(securityAnnotationName)) {
                            securityCheck = recorder.permitAll();
                        } else if (AUTHENTICATED.equals(securityAnnotationName)) {
                            securityCheck = recorder.authenticated();
                        } else if (ROLES_ALLOWED.equals(securityAnnotationName)) {
                            var allowedRoles = item.getSecurityAnnotationInstance().value().asStringArray();
                            securityCheck = computeRolesAllowedCheck(cache, hasRolesAllowedCheckWithConfigExp, keyIndex,
                                    recorder,
                                    allowedRoles);
                        } else if (PERMISSIONS_ALLOWED.equals(securityAnnotationName)) {
                            securityCheck = Objects.requireNonNull(classNameToPermCheck.get(item.getClassName()));
                        } else {
                            throw new IllegalStateException("Found unknown security annotation: " + securityAnnotationName);
                        }

                        classStorageBuilder.addSecurityCheck(item.getClassName(), securityCheck);
                    });
            classSecurityCheckStorageProducer.produce(classStorageBuilder.build());
        }

        final boolean registerRolesAllowedConfigSource;
        // way to resolve roles allowed configuration expressions specified via annotations to configuration values
        if (!rolesAllowedConfigExpResolverBuildItems.isEmpty()) {
            registerRolesAllowedConfigSource = true;
            for (RolesAllowedConfigExpResolverBuildItem item : rolesAllowedConfigExpResolverBuildItems) {
                recorder.recordRolesAllowedConfigExpression(item.getRoleConfigExpr(), keyIndex.getAndIncrement(),
                        item.getConfigValueRecorder());
            }
        } else {
            registerRolesAllowedConfigSource = hasRolesAllowedCheckWithConfigExp.get();
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Identify the annotation class from the error message and either replace it with a standard Quarkus annotation (@RolesAllowed, @PermissionsAllowed, @Authenticated, @DenyAll).
2. If it is a custom annotation, add the required build step / meta-annotation mapping (or annotate it with the Quarkus security annotation it should delegate to).
3. Align versions of all security-related extensions so their annotation processors match the core annotation set.

Example fix

// before
@MyCustomSecure
public String data() { ... }
// after
@RolesAllowed("admin")
public String data() { ... }

Set<String> allowed = Set.of("jakarta.annotation.security.RolesAllowed","io.quarkus.security.PermissionsAllowed","jakarta.annotation.security.DenyAll","jakarta.annotation.security.PermitAll","io.quarkus.security.Authenticated");
// fail fast if a security-looking annotation is not recognized
if (!allowed.contains(annotationName)) throw new IllegalStateException("unrecognized: " + annotationName);

When it happens

Trigger: A method or class carries a security annotation name that reaches gatherSecurityAnnotations but is not one of the handled constants (@RolesAllowed, @PermissionsAllowed, @DenyAll, @Authenticated, ...), typically from a custom meta-annotated annotation or a mismatched extension version.

Common situations: Using a third-party extension that adds its own security annotation without a corresponding build step; mixing Quarkus versions where security-annotations SPI changed; copying @CustomSecurity meta-annotation from a tutorial that required extra wiring.

Related errors

• @PermissionChecker annotation placed on the '%s' attribute '
• @PermissionChecker annotation instance placed on the '%s' re
• Detected two @PermissionChecker annotations with same value
• @PermissionChecker method '%s' declares checked exceptions w
• Permission class '%s' has %d constructors, exactly one is al

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