{"record":{"id":"1936d0576871783f","repo":"quarkusio/quarkus","slug":"roles-cannot-be-null-or-empty","errorCode":null,"errorMessage":"Roles cannot be null or empty","messagePattern":"Roles cannot be null or empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/security/MTLS.java","lineNumber":242,"sourceCode":"         * @see #rolesMapping(String, Set) for more information\n         */\n        public Builder rolesMapping(String certificateAttributeValue, String... roles) {\n            return rolesMapping(certificateAttributeValue, Set.of(roles));\n        }\n\n        /**\n         * Adds a certificate attribute value to roles mapping.\n         * The certificate attribute itself can be configured with the {@link #certificateAttribute} method.\n         *\n         * @param certificateAttributeValue {@link AuthRuntimeConfig#certificateRoleAttribute()} values that will be\n         *        mapped to the {@link SecurityIdentity} roles\n         * @param roles {@link SecurityIdentity#getRoles()}\n         * @return CertificateRolesBuilder\n         */\n        public Builder rolesMapping(String certificateAttributeValue, Set<String> roles) {\n            Objects.requireNonNull(certificateAttributeValue);\n            if (roles == null || roles.isEmpty()) {\n                throw new IllegalArgumentException(\"Roles cannot be null or empty\");\n            }\n            assertCertificateToRolesMapperNotSetYet();\n            if (certificateAttributeValueToRoles == null) {\n                certificateAttributeValueToRoles = new HashMap<>();\n            }\n            certificateAttributeValueToRoles.computeIfAbsent(certificateAttributeValue, new Function<String, Set<String>>() {\n                @Override\n                public Set<String> apply(String ignored) {\n                    return new HashSet<>();\n                }\n            }).addAll(roles);\n            return this;\n        }\n\n        private void assertCertificateToRolesMapperNotSetYet() {\n            if (certificateToRolesMapper != null) {\n                throw new IllegalStateException(\n                        \"The certificate to roles mapper is already configured with the 'certificateToRolesMapper' method\");","sourceCodeStart":224,"sourceCodeEnd":260,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/security/MTLS.java#L224-L260","documentation":"MTLS.Builder.rolesMapping(String, Set<String>) throws IllegalArgumentException when the roles set is null or empty. Each certificate attribute value must map to at least one role for the certificate-to-roles mapper to be meaningful.","triggerScenarios":"Calling rolesMapping(attrValue, null) or rolesMapping(attrValue, Set.of()) — e.g. when the role list comes from empty config or a failed lookup.","commonSituations":"Empty roles config entry; a role-list parsing step that filtered everything out; DB/property lookup returning no roles for a certificate attribute.","solutions":["Pass a non-empty Set of roles for each certificate attribute value","Skip calling rolesMapping when no roles are available","Fix the role source (config/lookup) to return actual role names"],"exampleFix":"// before\nbuilder.rolesMapping(\"CN=admin\", rolesFromConfig); // may be empty\n// after\nif (rolesFromConfig != null && !rolesFromConfig.isEmpty()) {\n    builder.rolesMapping(\"CN=admin\", rolesFromConfig);\n}","handlingStrategy":"validation","validationCode":"if (roles == null || roles.isEmpty()) {\n    throw new IllegalStateException(\"rolesMapping requires at least one role for \" + certAttrValue);\n}\nbuilder.rolesMapping(certAttrValue, roles);","typeGuard":"boolean hasRoles(Set<String> r) { return r != null && !r.isEmpty(); }","tryCatchPattern":null,"preventionTips":["Validate role config at startup so empty sets never reach the builder","Skip rolesMapping entries with no roles instead of registering them","Assert role sources return defaults rather than null/empty"],"tags":["quarkus","mtls","illegal-argument","roles","validation"],"backgroundTag":"invalid-argument-value","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"}