quarkusio/quarkus · error · IllegalStateException

Entity class ${fieldInfo.type().name()} referenced by ${this

Error message

Entity class ${fieldInfo.type().name()} referenced by ${this.entityClass}.${fieldPathBuilder} was not part of the Quarkus index${typed ? " or typed field could not be resolved properly. " : ". "}${offendingMethodMessage}

What it means

During nested field resolution, the type of an intermediate field (e.g. the target of an association) could not be found in the Quarkus Jandex index. This is an IllegalStateException because the entity graph cannot be traversed — either the class was not indexed or a typed (generic/parameterized) field could not be resolved.

Source

Thrown at extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/MethodNameParser.java:559

            if (fieldPathBuilder.length() > 0) {
                fieldPathBuilder.append('.');
            }
            fieldPathBuilder.append(fieldInfo.name());
            if (!isHibernateProvidedBasicType(fieldInfo.type().name())) {
                DotName parentClassName;
                boolean typed = false;
                if (fieldInfo.type().kind() == Type.Kind.TYPE_VARIABLE) {
                    typed = true;
                    parentClassName = getParentNameFromTypedFieldViaHierarchy(fieldInfo, mappedSuperClassInfos);
                } else if (fieldInfo.type().kind() == Type.Kind.PARAMETERIZED_TYPE) {
                    parentClassName = fieldInfo.type().asParameterizedType().arguments().stream().findFirst().get().name();
                } else {
                    parentClassName = fieldInfo.type().name();
                }
                parentClassInfo = indexView.getClassByName(parentClassName);
                parentSuperClassInfos.set(null);
                if (parentClassInfo == null) {
                    throw new IllegalStateException(
                            "Entity class " + fieldInfo.type().name() + " referenced by "
                                    + this.entityClass + "." + fieldPathBuilder
                                    + " was not part of the Quarkus index"
                                    + (typed ? " or typed field could not be resolved properly. " : ". ")
                                    + offendingMethodMessage);
                }

            }
            fieldStartIndex = fieldEndIndex;
        }
        return fieldInfo;
    }

    private int previousPotentialFieldEnd(String fieldName, int fieldStartIndex, int fieldEndIndexExclusive) {
        for (int i = fieldEndIndexExclusive - 1; i > fieldStartIndex; i--) {
            char c = fieldName.charAt(i);
            if (c >= 'A' && c <= 'Z') {
                return i;

View on GitHub (pinned to e1c734241f)

Solutions

Ensure the entity class's JAR is indexed by Quarkus (add quarkus-indexed dependencies or application.index dependencies for third-party entity jars)
Check that the association field is properly typed (e.g. Set<Address> not raw Set) so the parameterized type argument resolves
Rebuild with a clean build so the Jandex index includes all classes; verify the class appears in the index

Example fix

// before: raw/generic field prevents resolution
private Set addresses;
// after
private Set<Address> addresses;

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the association target is indexed; check the built app's index or add:
// quarkus.index-dependency.<name>.group-id / artifact-id in application.properties for third-party entity jars

Try / catch

try {
    // triggers augmentation/index lookup
    em.getEntityManagerFactory();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("was not part of the Quarkus index")) {
        throw new IllegalStateException("Add the entity jar to quarkus.index-dependency: " + e.getMessage());
    }
    throw e;
}

Prevention

Add quarkus.index-dependency.* entries for external JARs containing entities
Declare association fields with full parameterized types (Set<Address>, List<Order>)
Avoid runtime-generated entity classes; generate them before Quarkus indexing

When it happens

Trigger: Navigating an association in a derived method (e.g. findByAddress_City) where the Address class is not part of the application index (e.g. generated at runtime, in an unindexed jar, or lacking the relevant index inclusion); also for fields declared with type variables/raw types where the parameterized type argument cannot be resolved.

Common situations: Entities supplied by a third-party library whose JAR is not indexed; annotation processing generating entity classes after indexing; missing smallrye-index annotations or incorrect Quarkus index dependencies.

Related errors

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