quarkusio/quarkus · error · java.lang.RuntimeException

Found @PermissionChecker annotation instance that authorize

Error message

Found @PermissionChecker annotation instance that authorize the '%s' permission, however
                            no @PermissionsAllowed annotation instance requires this permission

What it means

A single @PermissionChecker was registered but no @PermissionsAllowed annotation requires its permission. Quarkus validates that every registered checker is actually consumed; an unconsumed checker is almost certainly a naming typo or leftover code, so the build fails. This is the singular variant of the unmatched-checker error.

Source

Thrown at extensions/security/deployment/src/main/java/io/quarkus/security/deployment/PermissionSecurityChecks.java:421

                                                clazz.name().toString(), String.class.getName()));
                            }
                            // rest of validation needs to be done for computed classes only and per each secured method
                            // therefore we do it later

                            // cache validation result
                            classSignatureToConstructor.put(key.classSignature(), constructor);
                        }
                    }
                }
            }
            if (!permissionCheckers.isEmpty()) {
                if (permissionCheckers.size() > 1) {
                    throw new RuntimeException("""
                            Found @PermissionChecker annotation instances that authorize the '%s' permissions, however
                            no @PermissionsAllowed annotation instance requires these permissions
                            """.formatted(String.join(",", permissionCheckers.values())));
                } else {
                    throw new RuntimeException("""
                            Found @PermissionChecker annotation instance that authorize the '%s' permission, however
                            no @PermissionsAllowed annotation instance requires this permission
                            """.formatted(permissionCheckers.values().iterator().next()));
                }
            }
            return this;
        }

        PermissionSecurityChecksBuilder gatherPermissionsAllowedAnnotations(
                Map<MethodInfo, AnnotationInstance> alreadyCheckedMethods,
                Map<ClassInfo, AnnotationInstance> alreadyCheckedClasses,
                List<AnnotationInstance> additionalClassInstances,
                Predicate<MethodInfo> hasAdditionalSecurityAnnotations) {

            List<PermissionKey> cache = new ArrayList<>();
            Map<MethodInfo, List<List<PermissionKey>>> classMethodToPermissionKeys = new HashMap<>();
            for (AnnotationInstance instance : permissionInstances) {

View on GitHub (pinned to e1c734241f)

Solutions

Add @PermissionsAllowed with the exact checker permission name to the protected method
Correct the permission string so the checker and requirement match character-for-character
Remove the @PermissionChecker method if the check is no longer needed

Example fix

// before
@PermissionChecker("book:read") boolean canRead(...) {...}
@PermissionsAllowed("books:read") public Book get(Long id) {...}

// after
@PermissionChecker("book:read") boolean canRead(...) {...}
@PermissionsAllowed("book:read") public Book get(Long id) {...}

Defensive patterns

Strategy: validation

Validate before calling

String checkerValue = "book:read";
if (!scanForPermissionsAllowedValues().contains(checkerValue))
    throw new IllegalStateException("No @PermissionsAllowed requires permission " + checkerValue);

Prevention

Extract permission names to shared constants used by both checker and @PermissionsAllowed
Before deleting a secured endpoint, delete its checker too
Run the application build locally before pushing; this error surfaces at build time

When it happens

Trigger: Declaring exactly one @PermissionChecker method whose 'value' does not appear in any @PermissionsAllowed in the application, found by validatePermissionClasses at build time.

Common situations: Typos in the permission string ('book:read' vs 'books:read'); deleting the secured endpoint during refactoring; moving @PermissionsAllowed to a different annotation value.

Related errors

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