{"record":{"id":"a1ff949b38239332","repo":"quarkusio/quarkus","slug":"roles-must-not-be-empty","errorCode":null,"errorMessage":"Roles must not be empty","messagePattern":"Roles must not be empty","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java","lineNumber":239,"sourceCode":"    }\n\n    @Override\n    public HttpPermission post(String... paths) {\n        return path(paths).methods(\"POST\");\n    }\n\n    @Override\n    public HttpPermission delete(String... paths) {\n        return path(paths).methods(\"DELETE\");\n    }\n\n    @Override\n    public HttpSecurity rolesMapping(Map<String, List<String>> roleToRoles) {\n        if (rolesMapping != null) {\n            throw new IllegalStateException(\"Roles mapping is already configured\");\n        }\n        if (roleToRoles == null || roleToRoles.isEmpty()) {\n            throw new IllegalArgumentException(\"Roles must not be empty\");\n        }\n        roleToRoles.forEach(new BiConsumer<String, List<String>>() {\n            @Override\n            public void accept(String sourceRole, List<String> targetRoles) {\n                if (sourceRole.isEmpty()) {\n                    throw new IllegalArgumentException(\"Source role must not be empty\");\n                }\n                if (targetRoles == null || targetRoles.isEmpty()) {\n                    throw new IllegalArgumentException(\"Target roles for role '%s' must not be empty\".formatted(sourceRole));\n                }\n            }\n        });\n\n        this.rolesMapping = RolesMapping.of(roleToRoles);\n        return this;\n    }\n\n    @Override","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java#L221-L257","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Only call rolesMapping when the map is non-null and non-empty: guard with if (roleToRoles != null && !roleToRoles.isEmpty()) httpSecurity.rolesMapping(roleToRoles);","Verify the source of the map (e.g. AuthRuntimeConfig role mappings) actually contains entries - check quarkus.http.auth.* config keys for typos.","If a mapping is optional, restructure the code to skip configuration rather than pass an empty map."],"exampleFix":"// before\nhttpSecurity.rolesMapping(config.rolesMapping()); // throws when empty\n// after\nMap<String, List<String>> mapping = config.rolesMapping();\nif (mapping != null && !mapping.isEmpty()) {\n    httpSecurity.rolesMapping(mapping);\n}","handlingStrategy":"validation","validationCode":"if (roleToRoles == null || roleToRoles.isEmpty()) {\n    // skip the call or throw a descriptive exception of your own\n    return;\n}\nhttpSecurity.rolesMapping(roleToRoles);","typeGuard":null,"tryCatchPattern":"try {\n    httpSecurity.rolesMapping(roleToRoles);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Skipping role mapping: \" + e.getMessage());\n}","preventionTips":["Never call rolesMapping with an empty map - skip the call instead.","Default-construct optional mapping config as null rather than an empty map so 'absent' is distinguishable.","Unit-test the config-to-HttpSecurity wiring with absent mapping sections."],"tags":["quarkus","http-security","argument-validation","illegal-argument"],"backgroundTag":"empty-argument-validation","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}