quarkusio/quarkus · error · IllegalStateException

Failed to index: ${name}

Error message

Failed to index: ${name}

What it means

To synthesize an annotation literal, the provider needs the Jandex ClassInfo of the annotation type. If it isn't in the application index, Quarkus tries to read and index the class bytecode from the build classloader; failure to load or index it (corrupt/missing class file, wrong classloader) raises this IllegalStateException with the class name.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/recording/AnnotationProxyProvider.java:68

        if (classLoader == null) {
            classLoader = AnnotationProxy.class.getClassLoader();
        }
        this.classLoader = classLoader;
    }

    public <A extends Annotation> AnnotationProxyBuilder<A> builder(AnnotationInstance annotationInstance,
            Class<A> annotationType) {
        if (!annotationInstance.name().toString().equals(annotationType.getName())) {
            throw new IllegalArgumentException("Annotation instance " + annotationInstance + " does not match annotation type "
                    + annotationType.getName());
        }
        ClassInfo annotationClass = annotationClasses.computeIfAbsent(annotationInstance.name(), name -> {
            ClassInfo clazz = index.getClassByName(name);
            if (clazz == null) {
                try (InputStream annotationStream = IoUtil.readClass(classLoader, name.toString())) {
                    clazz = Index.singleClass(annotationStream);
                } catch (Exception e) {
                    throw new IllegalStateException("Failed to index: " + name, e);
                }
            }
            return clazz;
        });
        String annotationLiteral = annotationLiterals.computeIfAbsent(annotationInstance.name(),
                // com.foo.MyAnnotation -> com.foo.MyAnnotation_Proxy_AnnotationLiteral
                name -> name + "_Proxy_AnnotationLiteral");

        return new AnnotationProxyBuilder<>(annotationInstance, annotationType, annotationLiteral, annotationClass);
    }

    public interface AnnotationProxy {

        String getAnnotationLiteralType();

        ClassInfo getAnnotationClass();

        AnnotationInstance getAnnotationInstance();

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the annotation type is on the build classpath and part of the indexed application classes
2. Check the 'Caused by' for the real read/index failure (ClassFormatError, IOException, etc.)
3. If the annotation is external, add its artifact as a deployment-time dependency so it gets indexed

ClassInfo ci = index.getClassByName(DotName.createSimple(MyAnno.class.getName()));
if (ci == null) { /* annotation not indexed; add artifact to build deps */ }

try {
    proxyProvider.builder(instance, MyAnno.class);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Failed to index:")) {
        // ensure annotation class is on build classpath and indexed
    }
}

When it happens

Trigger: builder() is called with an AnnotationInstance whose annotation class is absent from the application index and IoUtil.readClass + Index.singleClass throws — class not on the build classpath, array/primitive edge, or read/parse error.

Common situations: Annotation defined in a module not indexed by Quarkus; annotation coming from a JDK/internal package; shading/relocation breaking the class file lookup.

Related errors

• Failed to index: ${className}, class not present in class lo
• 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/3bb0fe0f3fc01612. Report an issue: GitHub.