quarkusio/quarkus · error · IllegalArgumentException

Permission value '${raw}' contains more than one unescaped c

Error message

Permission value '${raw}' contains more than one unescaped colon separator, use \: for a literal colon

What it means

The permission value format is 'name[:action]' — at most one unescaped colon separating the permission class from its action. A second unescaped colon means the parser cannot tell where the action begins, so it throws IllegalArgumentException. Use '\:' to embed a literal colon.

Source

Thrown at extensions/security/runtime-spi/src/main/java/io/quarkus/security/spi/runtime/PermissionToActionUtil.java:47

        char[] chars = raw.toCharArray();

        for (int i = 0; i < chars.length; i++) {
            switch (chars[i]) {
                case '\\':
                    if (++i == chars.length || chars[i] != ':') {
                        throw new IllegalArgumentException(
                                "Invalid escape sequence in permission value '" + raw
                                        + "': backslash is only allowed before a colon (\\:)");
                    }
                    if (foundSeparator) {
                        action.append(':');
                    } else {
                        name.append(':');
                    }
                    break;
                case ':':
                    if (foundSeparator) {
                        throw new IllegalArgumentException(
                                "Permission value '" + raw
                                        + "' contains more than one unescaped colon separator, use \\: for a literal colon");
                    }
                    foundSeparator = true;
                    break;
                default:
                    if (foundSeparator) {
                        action.append(chars[i]);
                    } else {
                        name.append(chars[i]);
                    }
            }
        }

        if (!foundSeparator) {
            return new ParsedPermissionImpl(name.toString(), null);
        }
        if (name.isEmpty()) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Use exactly one ':' separating class and action; express multiple actions with commas if the consumer supports it, e.g. 'com.app.Perm:read,write'.
2. Escape literal colons inside the name/action with '\:'.
3. Split into multiple permission entries instead of stuffing several into one value.

Example fix

# before
perm=com.app.Perm:read:write

# after
perm=com.app.Perm:read,write

int unescaped = 0;
for (int i = 0; i < raw.length(); i++) {
    char c = raw.charAt(i);
    if (c == '\\') { i++; continue; }
    if (c == ':') unescaped++;
}
boolean valid = unescaped <= 1;

try { PermissionToActionUtil.parse(raw); } catch (IllegalArgumentException e) { /* reduce to one unescaped colon */ }

When it happens

Trigger: A config value like 'com.a.Perm:read:write' or any value containing more than one raw colon passed to parse().

Common situations: Trying to express multiple actions in one entry separated by colons; permissions whose class name legitimately contains colons without escaping; copy-paste from URI-like strings.

Related errors

• Permission value must not be empty
• Invalid escape sequence in permission value '${raw}': backsl
• Could not obtain credential
• Could not obtain principal
• client-id, client-secret and introspection-url must be confi

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