quarkusio/quarkus · error · IllegalArgumentException

Class not in index:

Error message

Class not in index: 

What it means

FaultToleranceMethodSearch.findMethod walks a class's superclass chain in the Jandex index to resolve fault-tolerance methods (including generic type mappings). When a superclass in the chain is not present in the application's bean archive index, the build step cannot resolve the type mapping and throws IllegalArgumentException 'Class not in index: <name>'. This is a deployment-time (build) failure, not a runtime exception.

Source

Thrown at extensions/smallrye-fault-tolerance/deployment/src/main/java/io/quarkus/smallrye/faulttolerance/deployment/FaultToleranceMethodSearch.java:141

        // this is to satisfy the specification, which says: fallback method must be on the same class, a superclass
        // or an implemented interface of the class which declares the annotated method
        //
        // we fake this by checking that the matching method has the same name as one of the method declared on
        // the declaring class or any of its superclasses or any of its implemented interfaces (this is actually
        // quite precise, the only false positive would occur in presence of overloads)
        Set<String> declaredMethodNames = findDeclaredMethodNames(declaringClass);

        Deque<ClassWithTypeMapping> worklist = new ArrayDeque<>();
        {
            // add all superclasses first, so that they're preferred
            // interfaces are added during worklist iteration
            ClassInfo clazz = beanClass;
            TypeMapping typeMapping = new TypeMapping();
            worklist.add(new ClassWithTypeMapping(clazz, typeMapping));
            while (clazz.superName() != null) {
                ClassInfo superclass = index.getClassByName(clazz.superName());
                if (superclass == null) {
                    throw new IllegalArgumentException("Class not in index: " + clazz.superName());
                }
                Type genericSuperclass = clazz.superClassType();
                typeMapping = typeMapping.getDirectSupertypeMapping(superclass, genericSuperclass);
                worklist.add(new ClassWithTypeMapping(superclass, typeMapping));

                clazz = superclass;
            }
        }
        while (!worklist.isEmpty()) {
            ClassWithTypeMapping classWithTypeMapping = worklist.removeFirst();
            ClassInfo clazz = classWithTypeMapping.clazz;
            TypeMapping actualMapping = classWithTypeMapping.typeMapping;

            Set<MethodInfo> methods = getMethodsFromClass(clazz, name, expectedParameterTypes, expectedReturnType,
                    expectedExceptionParameter, declaringClass, actualMapping, expectedMapping);
            for (MethodInfo method : methods) {
                if (declaredMethodNames.contains(method.name())) {
                    result.add(method);

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the missing superclass jar is indexed: add quarkus.index-dependency.<name>.group-id/artifact-id in application.properties, or add a META-INF/beans.xml or META-INF/jandex.idx to that jar
2. If the superclass comes from your code, verify the module containing it is part of the application and compiled with the Quarkus Maven/Gradle plugin so it gets indexed
3. Avoid annotating classes whose hierarchy includes non-indexable classes (e.g. JDK classes); move the fault-tolerance annotations to the concrete, indexed bean class
4. Update io.quarkus:quarkus-smallrye-fault-tolerance and smallrye-fault-tolerance to the latest patch; if a normal user class triggers this on a supported setup, file a Quarkus bug with a reproducer

Example fix

// before (application.properties)
# dependency not indexed -> 'Class not in index: com.example.BaseService'
// after
quarkus.index-dependency.base.group-id=com.example
quarkus.index-dependency.base.artifact-id=base-lib

// Check before build that the bean's hierarchy is indexed
org.jboss.jandex.Index index = ...;
ClassInfo clazz = index.getClassByName(DotName.createSimple("com.example.MyBean"));
DotName superName = clazz.superName();
if (superName != null && index.getClassByName(superName) == null) {
    throw new IllegalStateException("Superclass not indexed: " + superName
        + " - add quarkus.index-dependency or jandex.idx");
}

When it happens

Trigger: A @ApplicationScoped (or otherwise indexed) bean annotated with fault-tolerance annotations (@Retry, @Fallback, @CircuitBreaker, etc.) extends a superclass that is not part of any Jandex index — typically a class from an un-indexed jar, a generated class, or a JDK/non-bean class absent from the index.

Common situations: Depending on a plain (non-Quarkus) library jar without a Jandex META-INF/jandex.idx and without adding it via quarkus.index-dependencies; running with -Dquarkus.index-dependency misconfigured; inheritance from framework classes that were never indexed; Quarkus/SmallRye Fault Tolerance version upgrades that started indexing additional hierarchies.

Related errors

• Injected class not found in index:
• Failed to process ${path}
• Failed to index: ${className}, class not present in class lo
• Annotation instance ${annotationInstance} does not match ann
• Failed to index: ${name}

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