quarkusio/quarkus · error · IllegalStateException

Failed to index: ${className}

Error message

Failed to index: ${className}

What it means

After successfully opening the class stream, indexClass calls indexer.indexWithSummary(stream); any exception during bytecode parsing is wrapped as IllegalStateException 'Failed to index: <className>'. This indicates malformed or unreadable class bytecode rather than a missing class.

Source

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

        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) {
            if (!additionalIndex.contains(annotationName) && quarkusIndex.getClassByName(annotationName) == null) {
                try (InputStream annotationStream = IoUtil.readClass(classLoader, annotationName.toString())) {
                    if (annotationStream == null) {
                        log.debugf("Could not index annotation: %s (missing class or dependency)", annotationName);
                        knownMissingClasses.add(annotationName);
                    } else {
                        log.debugf("Index annotation: %s", annotationName);
                        indexClass(annotationName.toString(), indexer, quarkusIndex, additionalIndex, knownMissingClasses,
                                classLoader);

View on GitHub (pinned to e1c734241f)

Solutions

1. Compile with a supported --release/-target (check Quarkus docs for max supported class file version) and rebuild
2. Run ./mvnw clean to remove corrupted target/classes and recompile
3. Remove or disable bytecode post-processing agents/obfuscators on the failing class
4. Upgrade Quarkus if the class genuinely uses a newer bytecode version and you need support for it

Example fix

// before
<properties><maven.compiler.release>99</maven.compiler.release></properties>
// after
<properties><maven.compiler.release>17</maven.compiler.release></properties>

// verify class file version before indexing
try (InputStream in = classLoader.getResourceAsStream(cls.replace('.','/') + ".class")) {
    DataInputStream d = new DataInputStream(in);
    int magic = d.readInt();
    d.readInt();
    int major = d.readUnsignedShort();
    if (magic != 0xCAFEBABE || major > 65 /* Java 21 */) throw new IllegalStateException("Unsupported/corrupt class file: " + cls + " major=" + major);
}

try {
    augment();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Failed to index:") && !e.getMessage().contains("class not present")) {
        // recompile the named class with a supported -target; check cause for ASM/UnsupportedClassVersionError
    }
    throw e;
}

When it happens

Trigger: indexClass() reading a class file whose bytecode cannot be parsed: corrupt class file, unsupported class file version (newer JDK bytecode than the embedded ASM), or IO error mid-read.

Common situations: Building with classes compiled by a newer JDK than Quarkus's supported bytecode level; corrupted class output after interrupted compile; bad/instrumented bytecode from weaving agents or obfuscators.

Related errors

• Failed to process ${path}
• Can't read Jandex index from ${tree}
• Failed to index: ${className}, class not present in class lo
• Failed to index: ${className}
• Failed to index: ${name}

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