quarkusio/quarkus · error · IllegalStateException

Failed to index: ${className}, class not present in class lo

Error message

Failed to index: ${className}, class not present in class loader: ${classLoader}

What it means

IndexingUtil.indexClass supplements the Quarkus index with classes not present in it; if IoUtil.readClass cannot find the class bytes in the given class loader, it throws IllegalStateException 'Failed to index: <class>, class not present in class loader: <cl>'. Quarkus needs the class bytecode to index its annotations/superclass for discovery.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/index/IndexingUtil.java:204

     * @deprecated use {@link LazyIndexer}
     */
    @Deprecated(since = "3.37", forRemoval = true)
    public static void indexClass(String className, Indexer indexer, IndexView quarkusIndex,
            Set<DotName> additionalIndex, Set<DotName> knownMissingClasses, ClassLoader classLoader) {
        DotName classDotName = DotName.createSimple(className);
        if (additionalIndex.contains(classDotName)) {
            return;
        }

        DotName superclassName;
        Set<DotName> annotationNames;

        ClassInfo classInfo = quarkusIndex.getClassByName(classDotName);
        if (classInfo == null) {
            log.debugf("Index class: %s", className);
            try (InputStream stream = IoUtil.readClass(classLoader, className)) {
                if (stream == null) {
                    throw new IllegalStateException(
                            "Failed to index: " + className + ", class not present in class loader: " + classLoader);
                }

                ClassSummary summary = indexer.indexWithSummary(stream);
                additionalIndex.add(summary.name());
                superclassName = summary.superclassName();
                annotationNames = summary.annotations();
            } catch (Exception e) {
                throw new IllegalStateException("Failed to index: " + className, e);
            }
        } else {
            // The class could be indexed by quarkus - we still need to distinguish framework classes
            additionalIndex.add(classDotName);
            superclassName = classInfo.superName();
            annotationNames = classInfo.annotationsMap().keySet();
        }

        for (DotName annotationName : annotationNames) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the missing dependency (correct artifact/scope: runtime instead of provided) so the class is on the runtime classpath
2. Rebuild (./mvnw clean install) to resync indexes with compiled classes
3. Check for shade/relocation: use the original class name or index the relocated one
4. If it's a framework-generated class expected at runtime, ensure the processor that generates it runs before indexing

Example fix

// before
<dependency><groupId>com.example</groupId><artifactId>lib</artifactId><scope>provided</scope></dependency>
// after
<dependency><groupId>com.example</groupId><artifactId>lib</artifactId><scope>runtime</scope></dependency>

Class<?> c;
try { c = Class.forName(className, false, classLoader); }
catch (ClassNotFoundException e) {
    throw new IllegalStateException("Add dependency providing " + className + " to the runtime classpath before building");
}

static boolean isLoadable(String className, ClassLoader cl) {
    return cl.getResource(className.replace('.', '/') + ".class") != null;
}

try {
    augment();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Failed to index:") && e.getMessage().contains("class not present in class loader")) {
        // parse className from message, check missing artifact/scope
    }
    throw e;
}

When it happens

Trigger: indexClass(classLoader, className, ...) when quarkusIndex.getClassByName returns null AND the class loader returns null from getResource for the .class file (IoUtil.readClass yields null).

Common situations: Optional/provided dependencies filtered out of the runtime classpath but referenced by an extension indexer; mismatch between the augmentation index and the runtime class loader (shaded/relocated classes); application classes removed by clean while dev mode still references them.

Related errors

• Failed to index: ${name}
• Unable to properly register the hierarchy of the following J
• 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/23be205c94b777d5. Report an issue: GitHub.