quarkusio/quarkus · error · IllegalArgumentException

Invalid escape sequence in permission value '${raw}': backsl

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.

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)

Solutions

1. Remove the stray backslash or replace it with the intended literal character.
2. Escape only literal colons as '\:' in the permission value.
3. 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

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 { PermissionToActionUtil.parse(raw); } catch (IllegalArgumentException e) { /* only \\ is allowed */ }

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

• Permission value must not be empty
• Permission value '${raw}' contains more than one unescaped c
• 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/9268aa4d03d58e30. Report an issue: GitHub.