quarkusio/quarkus · error · IllegalArgumentException

Invalid escape sequence in permission value

Error message

Invalid escape sequence in permission value '${raw}': backslash is only allowed before a colon (\:)

What it means

In the permission config value 'PermissionClass:action', a backslash is only meaningful as an escape for a literal colon ('\:'). Any other use of backslash makes parsing ambiguous, so parse() throws IllegalArgumentException.

Solutions

Remove the stray backslash or replace it with the intended literal character.
Escape only literal colons as '\:' in the permission value.
If a real backslash character is needed in the name, it is not supported by this parser; encode the value differently.

Example fix

# before
perm=com.example.My\Permission:read

# after
perm=com.example.MyPermission:read

Defensive patterns

Strategy: validation

Validate before calling

boolean validEscapes(String raw) {
    for (int i = 0; i < raw.length(); i++) {
        if (raw.charAt(i) == '\\' && (i + 1 >= raw.length() || raw.charAt(i + 1) != ':')) return false;
    }
    return true;
}

Try / catch

try { PermissionToActionUtil.parse(raw); } catch (IllegalArgumentException e) { /* only \\ is allowed */ }

Prevention

Only use backslash to escape colons
Don't paste Windows paths or regexes into permission values
Escape literal colons in class names

When it happens

Trigger: A permission config value containing a backslash not immediately followed by a colon, e.g. 'com.app.My\Permission:read' or a value ending with a trailing backslash.

Common situations: Windows-style paths or regex fragments pasted into permission config; attempting to escape other characters like '=' or '.' with backslash; generated config where a value containing backslashes was not re-escaped.

Related errors

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

Appendix: source

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

    private PermissionToActionUtil() {
    }

    public static ParsedPermission parse(String raw) {
        if (raw.isEmpty()) {
            throw new IllegalArgumentException("Permission value must not be empty");
        }

        var name = new StringBuilder();
        var action = new StringBuilder();
        boolean foundSeparator = false;
        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:

View on GitHub (pinned to e1c734241f)