quarkusio/quarkus · error · IllegalArgumentException

The class not found in the index

Error message

The class ${clazzName} not found in the index

What it means

ErrorCallbackArgument.isThrowable walks the class hierarchy of an @OnError callback parameter type in the Jandex index to decide whether it is a Throwable. If the class (or a supertype encountered while walking) is not present in the application index, the build fails with IllegalArgumentException. The index only contains application and dependency classes actually indexed.

Solutions

1. Ensure the artifact providing the exception class is indexed (add jandex-maven-plugin to its build, or use the '-jandex' classifier artifact if available)
2. Use a standard exception type (e.g. java.lang.Exception or an application-owned class) in the @OnError parameter
3. Upgrade the library — many popular libraries ship jandex indexes now
4. Verify the dependency is actually a compile/runtime dependency of the app, not missing

Example fix

// before
@OnError
void onError(SomeLibException e) { } // lib not Jandex-indexed
// after
@OnError
void onError(Throwable e) {
  if (e instanceof SomeLibException slEx) { ... }
}

// Verify the exception type is indexed before using it in @OnError
// mvn quarkus:build  # or check the jar for META-INF/jandex.idx
// If absent, add jandex-maven-plugin to the library or use Throwable

When it happens

Trigger: Declaring an @OnError parameter typed with a Throwable subclass that is not in the Jandex index (e.g. from a dependency without an index, or a dynamically referenced class).

Common situations: Using an exception type from a third-party library that ships no Jandex index (no META-INF/jandex.idx and not processed by the Jandex maven plugin); referencing generated exception classes not on the indexed classpath.

Related errors

• Enclosing class not found in index:
• ClassInfo not found for
• Couldn't find id field of
• Custom JDBC delegate implementation class
• Entity was not part of the Quarkus index

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

Appendix: source

Thrown at extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/ErrorCallbackArgument.java:28

    @Override
    public boolean matches(ParameterContext context) {
        return context.callbackAnnotation().name().equals(WebSocketDotNames.ON_ERROR)
                && isThrowable(context.index(), context.parameter().type().name());
    }

    @Override
    public Expr get(InvocationBytecodeContext context) {
        return context.getPayload();
    }

    boolean isThrowable(IndexView index, DotName clazzName) {
        if (clazzName.equals(WebSocketDotNames.THROWABLE)) {
            return true;
        }
        ClassInfo clazz = index.getClassByName(clazzName);
        if (clazz == null) {
            throw new IllegalArgumentException("The class " + clazzName + " not found in the index");
        }
        if (clazz.superName().equals(DotName.OBJECT_NAME)
                || clazz.superName().equals(DotName.RECORD_NAME)
                || clazz.superName().equals(DotName.ENUM_NAME)) {
            return false;
        }
        if (clazz.superName().equals(WebSocketDotNames.THROWABLE)) {
            return true;
        }
        return isThrowable(index, clazz.superName());
    }

    public static boolean isError(CallbackArgument callbackArgument) {
        return callbackArgument instanceof ErrorCallbackArgument;
    }

}

View on GitHub (pinned to e1c734241f)