{"record":{"id":"40a7b53e846a93c2","repo":"quarkusio/quarkus","slug":"role-to-roles-mapping-must-not-be-null","errorCode":null,"errorMessage":"Role to roles mapping must not be null","messagePattern":"Role to roles mapping must not be null","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":305,"sourceCode":"            this.policy = new Policy(PermitSecurityPolicy.NAME, null);\n            return HttpSecurityImpl.this;\n        }\n\n        @Override\n        public HttpSecurity deny() {\n            validatePolicyNotSetYet();\n            this.policy = new Policy(DenySecurityPolicy.NAME, null);\n            return HttpSecurityImpl.this;\n        }\n\n        @Override\n        public HttpSecurity roles(Map<String, List<String>> roleToRoles, String... roles) {\n            validatePolicyNotSetYet();\n            if (roles == null || roles.length == 0) {\n                throw new IllegalArgumentException(\"Roles must not be empty\");\n            }\n            if (roleToRoles == null) {\n                throw new IllegalArgumentException(\"Role to roles mapping must not be null\");\n            }\n            this.policy = new Policy(null, new RolesAllowedHttpSecurityPolicy(Arrays.asList(roles), null, roleToRoles));\n            return HttpSecurityImpl.this;\n        }\n\n        @Override\n        public HttpSecurity roles(String... roles) {\n            return roles(Map.of(), roles);\n        }\n\n        @Override\n        public HttpSecurity permissions(Permission... permissions) {\n            validatePolicyNotSetYet();\n            if (permissions == null || permissions.length == 0) {\n                throw new IllegalArgumentException(\"Permissions must not be empty\");\n            }\n            policy = new Policy(null, new PermissionsHttpSecurityPolicy(permissions));\n            return HttpSecurityImpl.this;","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java#L287-L323","documentation":"In the same roles(Map, String...) method, after the roles array is validated, a null roleToRoles map is rejected with IllegalArgumentException. Unlike the standalone rolesMapping method (which tolerates being skipped entirely), when you call this overload the mapping map itself is an explicit argument and must be non-null; it is handed directly to RolesAllowedHttpSecurityPolicy. An empty map appears to be accepted here - only null is rejected.","triggerScenarios":"httpSecurity.path(\"/x\").roles(null, \"admin\"); forwarding an uninitialized Map field; a lookup method returning null when no mapping exists for the path.","commonSituations":"Programmatic security setup where role-to-roles mapping is optional but the overload requires an explicit value; refactoring from the mapping-free overload and passing null instead of Map.of(); deserialization of a mapping object that was absent.","solutions":["Pass an explicit empty map (Map.of()) when there is no mapping, or use the roles-only overload if available.","Initialize the mapping variable to Map.of() by default rather than null.","Null-check the mapping source and substitute Map.of() at the call site."],"exampleFix":"// before\nhttpSecurity.path(\"/api/*\").roles(mapping, \"admin\"); // mapping may be null\n// after\nMap<String, List<String>> safeMapping =\n    mapping != null ? mapping : Map.of();\nhttpSecurity.path(\"/api/*\").roles(safeMapping, \"admin\");","handlingStrategy":"validation","validationCode":"Map<String, List<String>> safeMapping =\n    roleToRoles != null ? roleToRoles : Map.of();\nhttpSecurity.path(path).roles(safeMapping, roles);","typeGuard":"static <K, V> Map<K, V> orEmpty(Map<K, V> m) {\n    return m != null ? m : Map.of();\n}","tryCatchPattern":"try {\n    httpSecurity.path(\"/api/*\").roles(mapping, \"admin\");\n} catch (IllegalArgumentException e) {\n    log.error(\"roles() requires a non-null mapping: \" + e.getMessage());\n}","preventionTips":["Initialize mapping variables to Map.of() instead of null.","Never pass a raw nullable lookup result straight into the DSL.","Remember empty maps are fine here - only null is rejected."],"tags":["quarkus","http-security","rbac","null-check","argument-validation"],"backgroundTag":"null-argument-validation","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}