quarkusio/quarkus · error · ConfigurationException

Unable to properly register the hierarchy of the following J

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.

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)

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: ${className}, class not present in class lo
• Failed to index: ${name}
• Failed to process ${path}
• Can't read Jandex index from ${tree}
• Failed to index: ${className}

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