quarkusio/quarkus · error · IllegalStateException

${t.name()} is not in the Quarkus Jandex index and cannot be

Error message

${t.name()} is not in the Quarkus Jandex index and cannot be used as a query return type. Consider using a simpler type or ensure this class is properly indexed.

What it means

During augmentation, Quarkus verifies that the return type of a query method is resolvable in the Jandex index of the application. If the class named by the type (t.name()) is not found in the index, code generation cannot reason about it as a query result and the build fails with this IllegalStateException. Every class used as a query result must be part of the application (or a dependency) that Jandex indexes.

Source

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

    protected Type verifyQueryResultType(Type t, IndexView index) {
        if (isHibernateSupportedReturnType(t.name())) {
            return t;
        }
        if (t.kind() == Type.Kind.ARRAY) {
            return verifyQueryResultType(t.asArrayType().constituent(), index);
        } else if (t.kind() == Type.Kind.PARAMETERIZED_TYPE) {
            final List<Type> types = t.asParameterizedType().arguments();
            if (types.size() == 1 && isKnownContainerType(t.name())) {
                return verifyQueryResultType(types.get(0), index);
            } else {
                for (Type type : types) {
                    verifyQueryResultType(type, index);
                }
            }
        } else {
            final ClassInfo typeClass = index.getClassByName(t.name());
            if (typeClass == null) {
                throw new IllegalStateException(
                        t.name() + " is not in the Quarkus Jandex index and cannot be used as a query return type. " +
                                "Consider using a simpler type or ensure this class is properly indexed. ");
            }
        }
        return t;
    }

    private static boolean isKnownContainerType(DotName name) {
        return DotNames.LIST.equals(name)
                || DotNames.COLLECTION.equals(name)
                || DotNames.SET.equals(name)
                || DotNames.OPTIONAL.equals(name)
                || DotNames.STREAM.equals(name)
                || DotNames.ITERATOR.equals(name)
                || DotNames.SPRING_DATA_PAGE.equals(name)
                || DotNames.SPRING_DATA_SLICE.equals(name);
    }

View on GitHub (pinned to e1c734241f)

Solutions

Move the projection/DTO class into your application source so it gets indexed
If the class is in a dependency, add quarkus.index-dependency.<name>.group-id and quarkus.index-dependency.<name>.artifact-id in application.properties
Run 'mvn quarkus:index' (jandex-maven-plugin) on the library module to produce META-INF/jandex.idx
Use a simpler/indexed type (entity class or a local projection) instead

Example fix

// before (application.properties): dependency not indexed
# nothing
// after
quarkus.index-dependency.mydto.group-id=com.example
quarkus.index-dependency.mydto.artifact-id=my-dto-lib

Defensive patterns

Strategy: validation

Validate before calling

// Verify the return type is available to Jandex before using it in a repository
try (var is = Thread.currentThread().getContextClassLoader()
        .getResourceAsStream("com/example/MyProjection.class")) {
    if (is == null) throw new IllegalStateException("Return type not on classpath/index");
}
// or ensure quarkus.index-dependency.<name>.group-id/artifact-id is set for external libs

Try / catch

try {
    buildRepository();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("not in the Quarkus Jandex index")) {
        log.error("Index the class or move it into the app: " + e.getMessage());
    }
    throw e;
}

Prevention

Keep projection/DTO return types in your own application source
Register unindexed dependencies with quarkus.index-dependency.*
Run jandex-maven-plugin on library modules
Avoid exotic/generated classes as query return types

When it happens

Trigger: A repository finder returning a type from an unindexed jar (a dependency without a Jandex index / META-INF/jandex.idx and not registered via quarkus.index-dependency.*), a dynamically generated class, or a class outside the application's indexed classes.

Common situations: Projection classes living in a third-party library; forgetting quarkus.index-dependency.<name>.group-id/artifact config for an unindexed dependency; multi-module setups where the sibling module wasn't built with the Jandex index; using a JDK/external type (e.g. a DTO from a non-Quarkus lib) as a return type.

Related errors

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