quarkusio/quarkus · error · IllegalArgumentException

Target role for role '%s' must not be null

Error message

Target role for role '%s' must not be null

What it means

The two-string convenience overload rolesMapping(String sourceRole, String targetRole) rejects a null target role with an IllegalArgumentException naming the source role. It exists to let callers map a single source role to a single target role; after the check it delegates to rolesMapping(sourceRole, List.of(targetRole)) and then to the Map-based overload.

Source

Thrown at extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java:271

        this.rolesMapping = RolesMapping.of(roleToRoles);
        return this;
    }

    @Override
    public HttpSecurity rolesMapping(String sourceRole, List<String> targetRoles) {
        if (sourceRole == null) {
            throw new IllegalArgumentException("Source role must not be null");
        }
        if (targetRoles == null) {
            throw new IllegalArgumentException("Target roles for role '%s' must not be null".formatted(sourceRole));
        }
        return rolesMapping(Map.of(sourceRole, targetRoles));
    }

    @Override
    public HttpSecurity rolesMapping(String sourceRole, String targetRole) {
        if (targetRole == null) {
            throw new IllegalArgumentException("Target role for role '%s' must not be null".formatted(sourceRole));
        }
        return rolesMapping(sourceRole, List.of(targetRole));
    }

    void addHttpPermissions(List<HttpPermissionCarrier> httpPermissions) {
        this.httpPermissions.addAll(httpPermissions);
    }

    private final class AuthorizationPolicy implements Authorization {

        private Policy policy = null;

        @Override
        public HttpSecurity permit() {
            validatePolicyNotSetYet();
            this.policy = new Policy(PermitSecurityPolicy.NAME, null);
            return HttpSecurityImpl.this;
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass a non-null target role string.
2. Verify the value source (config key, constant) actually resolves before calling.
3. Guard with an if-check or Objects.requireNonNull(targetRole) at the call site to fail with clearer context.

Example fix

// before
httpSecurity.rolesMapping("user", config.adminRole()); // may be null
// after
String adminRole = config.adminRole();
if (adminRole != null) {
    httpSecurity.rolesMapping("user", adminRole);
}

if (targetRole != null) {
    httpSecurity.rolesMapping(sourceRole, targetRole);
}

static boolean canMap(String sourceRole, String targetRole) {
    return sourceRole != null && targetRole != null
        && !sourceRole.isBlank() && !targetRole.isBlank();
}

try {
    httpSecurity.rolesMapping("user", adminRole);
} catch (IllegalArgumentException e) {
    log.error("Invalid role mapping arguments: " + e.getMessage());
}

When it happens

Trigger: rolesMapping("user", null); passing a variable holding the target role that was not initialized or did not resolve from config; copy-pasted call sites where one argument was replaced with a null-returning method call.

Common situations: Simple identity-provider-to-application role mappings wired from properties where the target key was misspelled and returned null; refactors that changed a literal (e.g. "admin") into a config lookup that can return null.

Related errors

• Source role must not be null
• Target roles for role '%s' must not be null
• Source role must not be empty
• Target roles for role '%s' must not be empty
• Role to roles mapping must not be null

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