{"record":{"id":"f537b381bf9c60f2","repo":"quarkusio/quarkus","slug":"the-role-element-type-must-be-indexed-by-jandex","errorCode":null,"errorMessage":"The role element type must be indexed by Jandex: ${elementType}","messagePattern":"The role element type must be indexed by Jandex: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/security-jpa-common/deployment/src/main/java/io/quarkus/security/jpa/common/deployment/JpaSecurityIdentityUtil.java","lineNumber":171,"sourceCode":"                    // JpaIdentityProviderUtil.addRoles(builder, :role)\n                    bc.invokeStatic(\n                            MethodDesc.of(JpaIdentityProviderUtil.class, \"addRoles\", void.class,\n                                    QuarkusSecurityIdentity.Builder.class, String.class),\n                            builderVar, role);\n                    handledRole = true;\n                }\n                break;\n            case PARAMETERIZED_TYPE:\n                DotName roleType = rolesType.name();\n                if (roleType.equals(DotNames.LIST)\n                        || roleType.equals(DOTNAME_COLLECTION)\n                        || roleType.equals(DOTNAME_SET)) {\n                    Type elementType = rolesType.asParameterizedType().arguments().get(0);\n                    JpaSecurityDefinition.FieldOrMethod rolesFieldOrMethod;\n                    if (!elementType.name().equals(DotNames.STRING)) {\n                        ClassInfo roleClass = index.getClassByName(elementType.name());\n                        if (roleClass == null) {\n                            throw new RuntimeException(\n                                    \"The role element type must be indexed by Jandex: \" + elementType);\n                        }\n                        AnnotationTarget annotatedRolesValue = getSingleAnnotatedElement(index, DOTNAME_ROLES_VALUE);\n                        rolesFieldOrMethod = JpaSecurityDefinition.getFieldOrMethod(index, roleClass,\n                                annotatedRolesValue, panacheEntityPredicate.isPanache(roleClass));\n                        if (rolesFieldOrMethod == null) {\n                            throw new RuntimeException(\n                                    \"Missing @RoleValue annotation on (non-String) role element type: \" + elementType);\n                        }\n                    } else {\n                        rolesFieldOrMethod = null;\n                    }\n                    // for(:elementType roleElement : :role){\n                    //    JpaIdentityProviderUtil.addRoles(:role.roleField);\n                    //    // or for String collections:\n                    //    JpaIdentityProviderUtil.addRoles(:role);\n                    // }\n                    bc.forEach(role, (loopBody, var) -> {","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/security-jpa-common/deployment/src/main/java/io/quarkus/security/jpa/common/deployment/JpaSecurityIdentityUtil.java#L153-L189","documentation":"When the @Roles field/getter is a List/Collection/Set of a non-String element type, the role entity class must be present in the Jandex application index so the build-time generator can inspect its @RoleValue member. If index.getClassByName returns null the build fails.","triggerScenarios":"Declaring @Roles on a field of type List<MyRole> (or Set/Collection) where MyRole is not indexed by Jandex — e.g. the class comes from a binary dependency that is not indexed, is generated, or Quarkus cannot index the containing artifact.","commonSituations":"Role entity defined in a separate library JAR without a Jandex index (missing jandex-maven-plugin or META-INF/jandex.idx); role class generated at build time; using JDK/internal types as the element type.","solutions":["Ensure the role entity class is in your application source so Quarkus indexes it.","For classes in a dependency JAR, add a Jandex index: configure jandex-maven-plugin in that project, or add quarkus.index-dependency.* properties (quarkus.index-dependency.<name>.group-id/artifact-id) in application.properties.","Alternatively, store roles as List<String>/Set<String> so no role class indexing is needed."],"exampleFix":"// application.properties, role entity lives in an unindexed dependency\n// before\n# (role class not indexed)\n// after\nquarkus.index-dependency.my-roles.group-id=com.example\nquarkus.index-dependency.my-roles.artifact-id=role-entities","handlingStrategy":"validation","validationCode":"if (index.getClassByName(DotName.createSimple(\"com.example.Role\")) == null) {\n    throw new IllegalStateException(\"Role class not in Jandex index; add quarkus.index-dependency.*\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep role entities in the application module or in an indexed dependency.","Configure quarkus.index-dependency.<name>.group-id/artifact-id for external JARs.","Prefer List<String>/Set<String> roles when no entity is needed."],"tags":["quarkus","security-jpa","jandex","build-time"],"backgroundTag":"class-not-indexed","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"}