quarkusio/quarkus · error · ConfigurationException

Unable to properly register the hierarchy of the following…

Error message

Unable to properly register the hierarchy of the following JPA classes as they are not in the Jandex index:
${unindexedClasses}Consider adding them to the index either by creating a Jandex index for your dependency via the Maven plugin, an empty META-INF/beans.xml or quarkus.index-dependency properties.

What it means

Quarkus discovers and registers the JPA model (entities, mapped superclasses, embeddables) and their whole hierarchies from the Jandex index. When a superclass/interface/embeddable referenced by an indexed JPA class is itself not in the index (and cannot be ignored), JpaJandexScavenger throws a ConfigurationException listing the unindexed classes and how to index them.

Solutions

1. Add a quarkus.index-dependency entry in application.properties for the library (quarkus.index-dependency.<name>.group-id/artifact-id)
2. Add an empty META-INF/beans.xml to the dependency jar
3. Configure the jandex-maven-plugin in the library's pom.xml to generate META-INF/jandex.idx
4. If the classes come from your own project, ensure they are compiled as part of the application module

Example fix

// application.properties
// before
# nothing
// after
quarkus.index-dependency.entities.group-id=com.acme
quarkus.index-dependency.entities.artifact-id=entities

# application.properties — index the dependency before the build:
quarkus.index-dependency.entities.group-id=com.acme
quarkus.index-dependency.entities.artifact-id=entities
# or add an empty META-INF/beans.xml to the dependency jar

When it happens

Trigger: buildModelFromCollector (invoked by discoverModelAndRegisterForReflection / result) finds classes in the hierarchy of indexed JPA classes that are missing from the Jandex index and not in the ignorable set (e.g. not java.* types).

Common situations: Using entities from a third-party dependency without a Jandex index; adding an entity jar built without the jandex-maven-plugin, beans.xml, or quarkus.index-dependency entries; classes in a library jar produced outside Quarkus tooling.

Related errors

• Failed to index: , class not present in class loader
• Failed to index
• Annotation was not expected on a target of kind
• Can't load class
• Can't read Jandex index from

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

Appendix: source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/JpaJandexScavenger.java:139

        if (!collector.enumTypes.isEmpty()) {
            reflectiveClass.produce(ReflectiveClassBuildItem.builder("java.lang.Enum").methods().build());
            reflectiveClass.produce(ReflectiveClassBuildItem.builder(collector.enumTypes).methods().build());
        }

        // for the java types we collected (usually from java.time but it could be from other types),
        // we just register them for reflection
        reflectiveClass.produce(ReflectiveClassBuildItem.builder(collector.javaTypes).methods().build());

        if (!collector.unindexedClasses.isEmpty()) {
            Set<String> unIgnorableIndexedClasses = collector.unindexedClasses.stream().map(DotName::toString)
                    .collect(Collectors.toSet());
            unIgnorableIndexedClasses.removeAll(ignorableNonIndexedClasses);

            if (!unIgnorableIndexedClasses.isEmpty()) {
                final String unindexedClassesErrorMessage = unIgnorableIndexedClasses.stream().map(d -> "\t- " + d + "\n")
                        .collect(Collectors.joining());
                throw new ConfigurationException(
                        "Unable to properly register the hierarchy of the following JPA classes as they are not in the Jandex index:\n"
                                + unindexedClassesErrorMessage
                                + "Consider adding them to the index either by creating a Jandex index " +
                                "for your dependency via the Maven plugin, an empty META-INF/beans.xml or quarkus.index-dependency properties.");
            }
        }

        // Hibernate ORM will fall back to instantiating these types using reflection if they are not CDI beans,
        // so we need to enable that.
        forReflection = new ArrayList<>(collector.potentialCdiBeanTypes.size());
        for (DotName javaType : collector.potentialCdiBeanTypes) {
            forReflection.add(javaType.toString());
        }
        reflectiveClass.produce(ReflectiveClassBuildItem.builder(forReflection).constructors().build());

        return new JpaModelBuildItem(collector.packages, collector.entityTypes, managedClassNames,
                collector.potentialCdiBeanTypes, collector.xmlMappingsByPU);
    }

View on GitHub (pinned to e1c734241f)