What causes "Invalid @PermissionsAllowed value '%s': %s" in quarkusio/quarkus?

Fix the @PermissionsAllowed value string to valid syntax: a permission name optionally followed by action expressions, e.g. @PermissionsAllowed("get:single"), @PermissionsAllowed("create"), @PermissionsAllowed({"read", "update"}).

quarkusio/quarkus · error · java.lang.RuntimeException

Invalid @PermissionsAllowed value '%s': %s

Error message

Invalid @PermissionsAllowed value '%s': %s

What it means

Quarkus throws this at build time when a value inside @PermissionsAllowed cannot be parsed into a permission expression (name plus optional action list). PermissionToActionUtil.parse rejects malformed expressions (e.g. empty name, bad separator syntax, unbalanced quotes) and the builder wraps the parse failure in a RuntimeException that fails the deployment. It is a compile/deploy-time annotation validation, not a runtime security failure.

Source

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

        private <T extends AnnotationTarget> void gatherPermissionKeys(AnnotationInstance instance, T annotationTarget,
                List<PermissionKey> cache, Map<T, List<List<PermissionKey>>> targetToPermissionKeys) {
            boolean foundPermissionChecker = false;
            final var permissionToActions = new HashMap<PermissionNameAndChecker, Set<String>>();
            for (String permissionValExpression : instance.value().asStringArray()) {
                final PermissionCheckerMetadata checker = permissionNameToChecker.get(permissionValExpression);
                if (checker != null) {
                    // matched @PermissionAllowed("value") with @PermissionChecker("value")
                    foundPermissionChecker = true;
                    final var permissionNameKey = new PermissionNameAndChecker(permissionValExpression, checker);
                    if (!permissionToActions.containsKey(permissionNameKey)) {
                        permissionToActions.put(permissionNameKey, Collections.emptySet());
                    }
                } else {
                    final PermissionToActionUtil.ParsedPermission parsed;
                    try {
                        parsed = PermissionToActionUtil.parse(permissionValExpression);
                    } catch (IllegalArgumentException e) {
                        throw new RuntimeException(String.format(
                                "Invalid @PermissionsAllowed value '%s': %s",
                                permissionValExpression, e.getMessage()));
                    }
                    final PermissionNameAndChecker permissionNameKey = new PermissionNameAndChecker(parsed.name(),
                            null);
                    if (parsed.hasAction()) {
                        final String action = parsed.action();
                        if (permissionToActions.containsKey(permissionNameKey)) {
                            permissionToActions.get(permissionNameKey).add(action);
                        } else {
                            final Set<String> actions = new HashSet<>();
                            actions.add(action);
                            permissionToActions.put(permissionNameKey, actions);
                        }
                    } else {
                        if (!permissionToActions.containsKey(permissionNameKey)) {
                            permissionToActions.put(permissionNameKey, new HashSet<>());
                        }

View on GitHub (pinned to e1c734241f)

Solutions

Fix the @PermissionsAllowed value string to valid syntax: a permission name optionally followed by action expressions, e.g. @PermissionsAllowed("get:single"), @PermissionsAllowed("create"), @PermissionsAllowed({"read", "update"}).
Check the underlying IllegalArgumentException message in the error output — it names the exact parse problem (empty name, illegal character, etc.) and correct that part of the string.
If the value is built from constants, print/inspect the composed string to ensure it is not blank or malformed.
Consult the @PermissionsAllowed section of the Quarkus security guide for the accepted expression grammar of your Quarkus version.

Example fix

// before
@PermissionsAllowed("")
public String get() { ... }

// after
@PermissionsAllowed("get")
public String get() { ... }

Defensive patterns

Strategy: validation

Validate before calling

// Before deploying, validate each @PermissionsAllowed value parses:
// In a unit test:
@Test
void permissionsAllowedValuesParse() {
    for (String v : List.of("get:single", "create")) {
        assertDoesNotThrow(() -> io.quarkus.security.runtime.PermissionToActionUtil.parse(v));
    }
}

Prevention

Follow the documented 'name:action' expression syntax exactly; test annotation values in a unit test using PermissionToActionUtil.parse.
Avoid composing annotation values dynamically from nullable/blank strings.
After a Quarkus upgrade, re-check the security guide for grammar changes.

When it happens

Trigger: Annotating a method or class with @PermissionsAllowed whose 'value' string cannot be parsed by PermissionToActionUtil.parse, e.g. @PermissionsAllowed("=") , @PermissionsAllowed("-read"), or a name with an illegal permission-to-action separator form.

Common situations: Typos in the 'name:action' expression syntax; copying examples using wrong separators; concatenating strings or constants that produce empty/blank values; upgrading Quarkus and the expression grammar became stricter.

Related errors

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