{"record":{"id":"0ed1293c60069f29","repo":"karatelabs/karate","slug":"class-not-found-classname","errorCode":null,"errorMessage":"Class not found: <className>","messagePattern":"Class not found: <className>","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/Runner.java","lineNumber":685,"sourceCode":"         * Used for CLI --listener-factory option.\n         * @param className fully qualified class name\n         */\n        public Builder listenerFactory(String className) {\n            if (className != null && !className.isEmpty()) {\n                try {\n                    Class<?> clazz = Class.forName(className);\n                    Object instance = clazz.getDeclaredConstructor().newInstance();\n                    if (instance instanceof RunListenerFactory factory) {\n                        listenerFactories.add(factory);\n                    } else if (instance instanceof RunListener listener) {\n                        // If it's a RunListener, wrap it in a factory that returns the same instance\n                        listeners.add(listener);\n                    } else {\n                        throw new IllegalArgumentException(\n                                \"Class \" + className + \" must implement RunListenerFactory or RunListener\");\n                    }\n                } catch (ClassNotFoundException e) {\n                    throw new IllegalArgumentException(\"Class not found: \" + className, e);\n                } catch (Exception e) {\n                    throw new IllegalArgumentException(\"Failed to instantiate \" + className, e);\n                }\n            }\n            return this;\n        }\n\n        /**\n         * Add a result listener for streaming test results.\n         */\n        public Builder resultListener(ResultListener listener) {\n            if (listener != null) {\n                resultListeners.add(listener);\n            }\n            return this;\n        }\n\n        /**","sourceCodeStart":667,"sourceCodeEnd":703,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/Runner.java#L667-L703","documentation":"Runner.listenerFactory resolves listener class names via reflection; a ClassNotFoundException means the configured name does not exist on the classpath. It is rethrown as IllegalArgumentException with the original exception as cause.","triggerScenarios":"Runner.builder().listener(\"com.example.FooListener\") where the class is not compiled, misspelled, or its jar/module is absent at runtime.","commonSituations":"Typo or wrong package in the fully-qualified class name; test-scope listener referenced from main scope; dependency with the listener not declared in the runtime module; class moved/renamed after a refactor.","solutions":["Verify the fully-qualified class name (package + class) is exact","Confirm the class is on the runtime classpath of the module running Karate","Check compile errors — the listener may have failed to build","Search the classpath: unzip -l / locate the .class file for the named listener"],"exampleFix":"// before\nrunner.Builder.listener(\"com.example.Listeners\")\n// after\nrunner.Builder.listener(\"com.example.report.MyListener\")","handlingStrategy":"validation","validationCode":"try { Class.forName(name, false, classLoader); } catch (ClassNotFoundException e) { throw new IllegalStateException(\"listener not on classpath: \" + name, e); }","typeGuard":null,"tryCatchPattern":"try { builder.listener(name); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"Class not found:\")) { log.error(\"Check FQCN and classpath for {}\", name, e.getCause()); } throw e; }","preventionTips":["Store listener names as constants referencing Class.getCanonicalName()","Declare the listener's module/jar in the runtime scope, not just test scope","Grep the repo for the class before configuring by name"],"tags":["runner","listeners","classpath","reflection"],"backgroundTag":"class-not-found","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}