quarkusio/quarkus · error · IllegalArgumentException

Roles must not be empty

Error message

Roles must not be empty

What it means

HttpSecurity.rolesMapping(Map) requires a non-null, non-empty map of source-role to target-roles entries. The library throws IllegalArgumentException immediately so an effectively useless role mapping is never registered with the HTTP security policy. It is fail-fast argument validation on the fluent HttpSecurity API, typically consumed via addAuthRuntimeConfigToHttpSecurity from the Vert.x HTTP runtime config.

Source

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

    }

    @Override
    public HttpPermission post(String... paths) {
        return path(paths).methods("POST");
    }

    @Override
    public HttpPermission delete(String... paths) {
        return path(paths).methods("DELETE");
    }

    @Override
    public HttpSecurity rolesMapping(Map<String, List<String>> roleToRoles) {
        if (rolesMapping != null) {
            throw new IllegalStateException("Roles mapping is already configured");
        }
        if (roleToRoles == null || roleToRoles.isEmpty()) {
            throw new IllegalArgumentException("Roles must not be empty");
        }
        roleToRoles.forEach(new BiConsumer<String, List<String>>() {
            @Override
            public void accept(String sourceRole, List<String> targetRoles) {
                if (sourceRole.isEmpty()) {
                    throw new IllegalArgumentException("Source role must not be empty");
                }
                if (targetRoles == null || targetRoles.isEmpty()) {
                    throw new IllegalArgumentException("Target roles for role '%s' must not be empty".formatted(sourceRole));
                }
            }
        });

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

    @Override

View on GitHub (pinned to e1c734241f)

Solutions

1. Only call rolesMapping when the map is non-null and non-empty: guard with if (roleToRoles != null && !roleToRoles.isEmpty()) httpSecurity.rolesMapping(roleToRoles);
2. Verify the source of the map (e.g. AuthRuntimeConfig role mappings) actually contains entries - check quarkus.http.auth.* config keys for typos.
3. If a mapping is optional, restructure the code to skip configuration rather than pass an empty map.

Example fix

// before
httpSecurity.rolesMapping(config.rolesMapping()); // throws when empty
// after
Map<String, List<String>> mapping = config.rolesMapping();
if (mapping != null && !mapping.isEmpty()) {
    httpSecurity.rolesMapping(mapping);
}

if (roleToRoles == null || roleToRoles.isEmpty()) {
    // skip the call or throw a descriptive exception of your own
    return;
}
httpSecurity.rolesMapping(roleToRoles);

try {
    httpSecurity.rolesMapping(roleToRoles);
} catch (IllegalArgumentException e) {
    log.warn("Skipping role mapping: " + e.getMessage());
}

When it happens

Trigger: Calling rolesMapping(null); calling rolesMapping(Map.of()) or an empty HashMap; programmatically building the map from config where quarkus.http.auth.permission.*.roles or policy role mappings resolved to nothing; passing a map whose entries were all filtered out before the call.

Common situations: Building HttpSecurity programmatically from application properties where an optional role-mapping section is absent and an empty map is passed instead of skipping the call; refactoring code that conditionally populated roleToRoles; copy-pasting a rolesMapping call and forgetting to populate entries.

Related errors

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

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