{"record":{"id":"23be205c94b777d5","repo":"quarkusio/quarkus","slug":"failed-to-index-classname-class-not-present-i","errorCode":null,"errorMessage":"Failed to index: ${className}, class not present in class loader: ${classLoader}","messagePattern":"Failed to index: (.+?), class not present in class loader: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/deployment/src/main/java/io/quarkus/deployment/index/IndexingUtil.java","lineNumber":204,"sourceCode":"     * @deprecated use {@link LazyIndexer}\n     */\n    @Deprecated(since = \"3.37\", forRemoval = true)\n    public static void indexClass(String className, Indexer indexer, IndexView quarkusIndex,\n            Set<DotName> additionalIndex, Set<DotName> knownMissingClasses, ClassLoader classLoader) {\n        DotName classDotName = DotName.createSimple(className);\n        if (additionalIndex.contains(classDotName)) {\n            return;\n        }\n\n        DotName superclassName;\n        Set<DotName> annotationNames;\n\n        ClassInfo classInfo = quarkusIndex.getClassByName(classDotName);\n        if (classInfo == null) {\n            log.debugf(\"Index class: %s\", className);\n            try (InputStream stream = IoUtil.readClass(classLoader, className)) {\n                if (stream == null) {\n                    throw new IllegalStateException(\n                            \"Failed to index: \" + className + \", class not present in class loader: \" + classLoader);\n                }\n\n                ClassSummary summary = indexer.indexWithSummary(stream);\n                additionalIndex.add(summary.name());\n                superclassName = summary.superclassName();\n                annotationNames = summary.annotations();\n            } catch (Exception e) {\n                throw new IllegalStateException(\"Failed to index: \" + className, e);\n            }\n        } else {\n            // The class could be indexed by quarkus - we still need to distinguish framework classes\n            additionalIndex.add(classDotName);\n            superclassName = classInfo.superName();\n            annotationNames = classInfo.annotationsMap().keySet();\n        }\n\n        for (DotName annotationName : annotationNames) {","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/deployment/src/main/java/io/quarkus/deployment/index/IndexingUtil.java#L186-L222","documentation":"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.","triggerScenarios":"indexClass(classLoader, className, ...) when quarkusIndex.getClassByName returns null AND the class loader returns null from getResource for the .class file (IoUtil.readClass yields null).","commonSituations":"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.","solutions":["Add the missing dependency (correct artifact/scope: runtime instead of provided) so the class is on the runtime classpath","Rebuild (./mvnw clean install) to resync indexes with compiled classes","Check for shade/relocation: use the original class name or index the relocated one","If it's a framework-generated class expected at runtime, ensure the processor that generates it runs before indexing"],"exampleFix":"// before\n<dependency><groupId>com.example</groupId><artifactId>lib</artifactId><scope>provided</scope></dependency>\n// after\n<dependency><groupId>com.example</groupId><artifactId>lib</artifactId><scope>runtime</scope></dependency>","handlingStrategy":"validation","validationCode":"Class<?> c;\ntry { c = Class.forName(className, false, classLoader); }\ncatch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Add dependency providing \" + className + \" to the runtime classpath before building\");\n}","typeGuard":"static boolean isLoadable(String className, ClassLoader cl) {\n    return cl.getResource(className.replace('.', '/') + \".class\") != null;\n}","tryCatchPattern":"try {\n    augment();\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Failed to index:\") && e.getMessage().contains(\"class not present in class loader\")) {\n        // parse className from message, check missing artifact/scope\n    }\n    throw e;\n}","preventionTips":["Prefer 'runtime' scope over 'provided' for classes needed at runtime by extensions","Run mvn dependency:tree to confirm the artifact supplying the class is present","Do mvn clean install after removing/renaming classes so indexes and class loaders stay in sync"],"tags":["jandex","classpath","indexing"],"backgroundTag":"class-not-found-in-classloader","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}