quarkusio/quarkus · error · IllegalArgumentException

The class ${clazzName} 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.

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)

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:
• Invalid type:
• Injected class not found in index:
• The original implementation class of a gRPC service not foun
• Couldn't find id field of ${classInfo}

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