quarkusio/quarkus · error · IllegalStateException

Unable to find the bean class in the index:

Error message

Unable to find the bean class in the index: 

What it means

BeanConfigurator.done() finalizes a synthetic bean configurator. It looks up the configured implementation class (implClazz) in the bean archive index; if the class is not in any indexed bean archive it throws IllegalStateException, because Arc needs the ClassInfo (annotations, members) to build the bean metadata.

Source

Thrown at independent-projects/arc/processor/src/main/java/io/quarkus/arc/processor/BeanConfigurator.java:50

     * @param implClassName
     * @param beanDeployment
     * @param beanConsumer
     */
    BeanConfigurator(DotName implClassName, BeanDeployment beanDeployment, Consumer<BeanInfo> beanConsumer) {
        super(implClassName);
        this.consumed = new AtomicBoolean(false);
        this.beanDeployment = beanDeployment;
        this.beanConsumer = beanConsumer;
    }

    /**
     * Finish the configurator. The configurator should not be modified after this method is called.
     */
    public void done() {
        if (consumed.compareAndSet(false, true)) {
            ClassInfo implClass = getClassByName(beanDeployment.getBeanArchiveIndex(), Objects.requireNonNull(implClazz));
            if (implClass == null) {
                throw new IllegalStateException("Unable to find the bean class in the index: " + implClazz);
            }

            ScopeInfo scope = this.scope;
            if (scope == null) {
                scope = Beans.initStereotypeScope(stereotypes, implClass, beanDeployment);
            }
            if (scope == null) {
                scope = BuiltinScope.DEPENDENT.getInfo();
            }

            String name = this.name;
            if (name == null) {
                name = Beans.initStereotypeName(stereotypes, implClass, beanDeployment);
            }

            Boolean alternative = this.alternative;
            if (alternative == null) {
                alternative = Beans.initStereotypeAlternative(stereotypes, beanDeployment);

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the class to a bean archive / ensure it's part of the application index (add beans.xml or @QuarkusMain/app classes)
2. Use the actual bean class as implClazz (a class inside an indexed archive), or use creator(Class) with a BeanCreator instead of implClazz
3. Check the Jandex index includes the JAR (Quarkus: add the library as a dependency so it's indexed, or add index via jandex-maven-plugin)
4. Verify the class name (no typos, correct package) and that the class exists at deployment time

Example fix

// before
configurator.implClazz(SomeLibClass.class).done(); // not indexed
// after
configurator.creator(SomeLibClassCreator.class) // BeanCreator impl, no index lookup needed
           .done();

DotName name = DotName.createSimple(SomeClass.class.getName());
if (beanDeployment.getBeanArchiveIndex().getClassByName(name) == null) {
    throw new IllegalStateException(SomeClass.class + " is not in a bean archive index");
}

try { configurator.done(); }
catch (IllegalStateException e) { throw new DeploymentException("implClazz not indexed: use a bean-archive class or a BeanCreator", e); }

When it happens

Trigger: registerSyntheticBeans()/configureSyntheticBean() with an impl class that is not indexed — the class lives in a non-bean-archive JAR, isn't in Jandex index, or the name/class mismatch (wrong DotName or class loaded but not indexed).

Common situations: Synthetic beans whose 'implClazz' points at a class from a library not registered as a bean archive; GraalVM/native-image index gaps; forgetting @Injectable or bean-archive marker so the class isn't indexed; refactors moving the class out of the app.

Related errors

• Annotation class not available:
• Annotation does not have @Retention(RUNTIME):
• Value is not set for %s.%s(). Most probably an older version
• Class of nested annotation missing
• Array component kind is

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