{"record":{"id":"342f18880aa91cf3","repo":"quarkusio/quarkus","slug":"the-class-clazzname-not-found-in-the-index","errorCode":null,"errorMessage":"The class ${clazzName} not found in the index","messagePattern":"The class (.+?) not found in the index","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/ErrorCallbackArgument.java","lineNumber":28,"sourceCode":"\n    @Override\n    public boolean matches(ParameterContext context) {\n        return context.callbackAnnotation().name().equals(WebSocketDotNames.ON_ERROR)\n                && isThrowable(context.index(), context.parameter().type().name());\n    }\n\n    @Override\n    public Expr get(InvocationBytecodeContext context) {\n        return context.getPayload();\n    }\n\n    boolean isThrowable(IndexView index, DotName clazzName) {\n        if (clazzName.equals(WebSocketDotNames.THROWABLE)) {\n            return true;\n        }\n        ClassInfo clazz = index.getClassByName(clazzName);\n        if (clazz == null) {\n            throw new IllegalArgumentException(\"The class \" + clazzName + \" not found in the index\");\n        }\n        if (clazz.superName().equals(DotName.OBJECT_NAME)\n                || clazz.superName().equals(DotName.RECORD_NAME)\n                || clazz.superName().equals(DotName.ENUM_NAME)) {\n            return false;\n        }\n        if (clazz.superName().equals(WebSocketDotNames.THROWABLE)) {\n            return true;\n        }\n        return isThrowable(index, clazz.superName());\n    }\n\n    public static boolean isError(CallbackArgument callbackArgument) {\n        return callbackArgument instanceof ErrorCallbackArgument;\n    }\n\n}\n","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/ErrorCallbackArgument.java#L10-L46","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Ensure the artifact providing the exception class is indexed (add jandex-maven-plugin to its build, or use the '-jandex' classifier artifact if available)","Use a standard exception type (e.g. java.lang.Exception or an application-owned class) in the @OnError parameter","Upgrade the library — many popular libraries ship jandex indexes now","Verify the dependency is actually a compile/runtime dependency of the app, not missing"],"exampleFix":"// before\n@OnError\nvoid onError(SomeLibException e) { } // lib not Jandex-indexed\n// after\n@OnError\nvoid onError(Throwable e) {\n  if (e instanceof SomeLibException slEx) { ... }\n}","handlingStrategy":"validation","validationCode":"// Verify the exception type is indexed before using it in @OnError\n// mvn quarkus:build  # or check the jar for META-INF/jandex.idx\n// If absent, add jandex-maven-plugin to the library or use Throwable","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer application-owned or JDK exception types in @OnError params","Ensure third-party libs ship jandex indexes or use the -jandex classifier","Catch a broad Throwable and instanceof-narrow inside the handler"],"tags":["quarkus","websockets-next","jandex","build-time"],"backgroundTag":"class-not-found-in-index","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}