quarkusio/quarkus · error · RuntimeException

Class '%s' was not found

Error message

Class '%s' was not found

What it means

During the rest-links build step, validateClassHasFieldId looks up the entity type of a resource method in the Jandex index to verify it has an id. If the entity class is not in the application index (not part of the application's classes/beans-archive), a RuntimeException 'Class %s was not found' is thrown and the build fails.

Source

Thrown at extensions/resteasy-reactive/rest-links/deployment/src/main/java/io/quarkus/resteasy/reactive/links/deployment/LinksProcessor.java:230

            if (annotationInstance.name().toString().endsWith(annotation)) {
                return true;
            }
        }
        return false;
    }

    /**
     * Validates if the given classname contains a field `id` or annotated with `@Id`
     *
     * @throws IllegalStateException if the classname does not contain any sort of field identifier
     */
    private void validateClassHasFieldId(IndexView index, String entityType) {
        // create a new independent class name that we can override
        DotName className = DotName.createSimple(entityType);
        ClassInfo classInfo = index.getClassByName(className);

        if (classInfo == null) {
            throw new RuntimeException(String.format("Class '%s' was not found", className));
        }
        validateRec(index, entityType, classInfo);
    }

    /**
     * Validates if the given classname contains a field `id` or annotated with `@Id`
     *
     * @throws IllegalStateException if the classname does not contain any sort of field identifier
     */
    private void validateRec(IndexView index, String entityType, ClassInfo classInfo) {
        List<FieldInfo> fieldsNamedId = classInfo.fields().stream()
                .filter(f -> f.name().equals("id"))
                .toList();

        List<AnnotationInstance> fieldsAnnotatedWithId = classInfo.fields().stream()
                .flatMap(f -> f.annotations().stream())
                .filter(a -> a.name().toString().endsWith("persistence.Id"))
                .toList();

View on GitHub (pinned to e1c734241f)

Solutions

1. Add a Jandex index to the library containing the class (jandex-maven-plugin / io.quarkus:quarkus-extension-processor, or quarkus.index-dependencies.* config).
2. Ensure the class is in your application source so it is indexed automatically.
3. Check the configured entity type name is correct and the jar is on the application classpath.

Example fix

// before: external jar without index
// after (library pom.xml)
<plugin>
  <groupId>io.smallrye</groupId>
  <artifactId>jandex-maven-plugin</artifactId>
  <executions><execution><id>make-index</id><goals><goal>jandex</goal></goals></execution></executions>
</plugin>

// ensure entity jar is indexed
// mvn jandex:jandex on the library, or verify META-INF/jandex.idx exists in the jar
unzip -l shared-entities.jar | grep jandex.idx

When it happens

Trigger: A REST resource method whose entity/path parameter type is not indexed — e.g. the class comes from a jar without a Jandex index (missing jandex-maven-plugin or META-INF/jandex.idx), or the type name is wrong/unresolvable.

Common situations: Using a DTO/entity from an external library jar without a Jandex index; generated classes not added to the index; multi-module builds where the entity module was not indexed.

Related errors

• Failed to process ${path}
• Annotation instance ${annotationInstance} does not match ann
• The class is not inside the Jandex index
• TransformedAnnotationsBuildItem#queryForMethodParam needs to
• Invalid type:

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