What causes "Entity ${entity} was not part of the Quarkus index" in quarkusio/quarkus?

Put the entity class in the application's own source tree, or index its containing JAR (jandex-maven-plugin producing META-INF/jandex.idx, or quarkus.index-dependency. .coordinates in application.properties)

quarkusio/quarkus · error · IllegalStateException

Entity ${entity} was not part of the Quarkus index

Error message

Entity ${entity} was not part of the Quarkus index

What it means

When generating a CRUD repository implementation, Quarkus resolves the entity type from the repository's generic signature and then looks the entity class up in the Jandex index. This error means the entity class resolved from generics was not found in the index, so its fields/methods cannot be inspected to generate queries.

Source

Thrown at extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/generate/SpringDataRepositoryCreator.java:67

        this.stockMethodsAdder = new StockMethodsAdder(index, typeBundle);
        this.derivedMethodsAdder = new DerivedMethodsAdder(index, typeBundle, otherClassOutput, customClassCreatedCallback);

        // custom queries may generate non-bean classes
        this.customQueryMethodsAdder = new CustomQueryMethodsAdder(index, otherClassOutput, customClassCreatedCallback,
                typeBundle);
    }

    public Result implementCrudRepository(ClassInfo repositoryToImplement, IndexView indexView) {
        Map.Entry<DotName, DotName> extraTypesResult = extractIdAndEntityTypes(repositoryToImplement, indexView);

        DotName idTypeDotName = extraTypesResult.getKey();
        String idTypeStr = idTypeDotName.toString();
        DotName entityDotName = extraTypesResult.getValue();
        String entityTypeStr = entityDotName.toString();

        ClassInfo entityClassInfo = index.getClassByName(entityDotName);
        if (entityClassInfo == null) {
            throw new IllegalStateException("Entity " + entityDotName + " was not part of the Quarkus index");
        }

        // handle the fragment repositories
        // Spring Data allows users to define (and implement their own interfaces containing data access related methods)
        // that can then be used along with any of the typical Spring Data repository interfaces in the final
        // repository in order to compose functionality

        List<DotName> interfaceNames = repositoryToImplement.interfaceNames();
        List<DotName> fragmentNamesToImplement = new ArrayList<>(interfaceNames.size());
        for (DotName interfaceName : interfaceNames) {
            if (!DotNames.SUPPORTED_REPOSITORIES.contains(interfaceName)
                    && !GenerationUtil.isIntermediateRepository(interfaceName, indexView)) {
                fragmentNamesToImplement.add(interfaceName);
            }
        }

        Map<String, FieldDesc> fragmentImplNameToFieldDescriptor = new HashMap<>();
        String repositoryToImplementStr = repositoryToImplement.name().toString();

View on GitHub (pinned to e1c734241f)

Solutions

Put the entity class in the application's own source tree, or index its containing JAR (jandex-maven-plugin producing META-INF/jandex.idx, or quarkus.index-dependency.<name>.coordinates in application.properties)
Verify the repository's entity generic parameter is the concrete @Entity class actually used by the persistence unit
Run a clean rebuild to refresh the index

Example fix

// application.properties
// before: dependency un-indexed
// after:
quarkus.index-dependency.entities.group-id=com.example
quarkus.index-dependency.entities.artifact-id=my-entities

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the entity referenced by the repository is an application class or an indexed dependency
// repository: interface UserRepo extends CrudRepository<User, Long>
assert new java.io.File("src/main/java/com/example/User.java").exists()
  || pomContainsIndexDependency("com.example","my-entities");

Prevention

Keep @Entity classes in the application or in JARs built with the jandex-maven-plugin
Register entity-only dependencies via quarkus.index-dependency.*
Always use the concrete @Entity class as the repository's first generic argument

When it happens

Trigger: A repository extends CrudRepository/Repository with an entity type parameter that resolves to a class not present in the build-time index — e.g. entity defined in an un-indexed dependency JAR, or a generated class not yet on the index.

Common situations: Entities in a separate module/JAR without a Jandex index; wrong generic parameter (interface or abstract class from another library); stale incremental build; entities produced by annotation processing not indexed.

Related errors

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