karatelabs/karate · error · IllegalArgumentException

Class not found

Error message

Class not found: <className>

What it means

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.

Solutions

1. Verify the fully-qualified class name (package + class) is exact
2. Confirm the class is on the runtime classpath of the module running Karate
3. Check compile errors — the listener may have failed to build
4. Search the classpath: unzip -l / locate the .class file for the named listener

Example fix

// before
runner.Builder.listener("com.example.Listeners")
// after
runner.Builder.listener("com.example.report.MyListener")

try { Class.forName(name, false, classLoader); } catch (ClassNotFoundException e) { throw new IllegalStateException("listener not on classpath: " + name, e); }

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; }

When it happens

Trigger: Runner.builder().listener("com.example.FooListener") where the class is not compiled, misspelled, or its jar/module is absent at runtime.

Common situations: 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.

Related errors

• Failed to instantiate
• Class must implement RunListenerFactory or RunListener
• failed to start debug server
• Failed to deserialize JSON to
• boot.read: file not found

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/0ed1293c60069f29. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/Runner.java:685

         * Used for CLI --listener-factory option.
         * @param className fully qualified class name
         */
        public Builder listenerFactory(String className) {
            if (className != null && !className.isEmpty()) {
                try {
                    Class<?> clazz = Class.forName(className);
                    Object instance = clazz.getDeclaredConstructor().newInstance();
                    if (instance instanceof RunListenerFactory factory) {
                        listenerFactories.add(factory);
                    } else if (instance instanceof RunListener listener) {
                        // If it's a RunListener, wrap it in a factory that returns the same instance
                        listeners.add(listener);
                    } else {
                        throw new IllegalArgumentException(
                                "Class " + className + " must implement RunListenerFactory or RunListener");
                    }
                } catch (ClassNotFoundException e) {
                    throw new IllegalArgumentException("Class not found: " + className, e);
                } catch (Exception e) {
                    throw new IllegalArgumentException("Failed to instantiate " + className, e);
                }
            }
            return this;
        }

        /**
         * Add a result listener for streaming test results.
         */
        public Builder resultListener(ResultListener listener) {
            if (listener != null) {
                resultListeners.add(listener);
            }
            return this;
        }

        /**

View on GitHub (pinned to a22eb90246)