karatelabs/karate · error · IllegalArgumentException

Failed to instantiate

Error message

Failed to instantiate <className>

What it means

After successfully loading the listener class, listenerFactory attempts to instantiate it via a no-arg constructor; any failure (instantiation/access exception) is wrapped in 'Failed to instantiate <className>'. The class exists but cannot be constructed in this context.

Solutions

1. Add a public no-arg constructor to the listener class
2. Check the constructor body for exceptions (read the wrapped cause) — e.g. missing files or config it reads at init
3. Make the class concrete (not abstract/interface) and public
4. If it's a non-static inner class, make it static or top-level

Example fix

// before
public class MyListener {
    public MyListener(Path cfg) { ... }
}
// after
public class MyListener {
    public MyListener() { this(defaultCfg()); }
    public MyListener(Path cfg) { ... }
}

Class<?> c = Class.forName(name);
if (Modifier.isAbstract(c.getModifiers()) || c.isInterface() || c.getConstructors().length == 0)
    throw new IllegalStateException("listener lacks a public constructor: " + name);
c.getDeclaredConstructor().newInstance(); // dry-run check

boolean instantiable(Class<?> c) { try { c.getDeclaredConstructor().newInstance(); return true; } catch (ReflectiveOperationException e) { return false; } }

try { builder.listener(name); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Failed to instantiate")) { log.error("{} needs a public no-arg constructor; cause: {}", name, e.getCause()); } throw e; }

When it happens

Trigger: Thrown at karate-core/src/main/java/io/karatelabs/core/Runner.java:687 when the library encounters an invalid state.

Common situations: Listener has no public no-arg constructor (only parameterized ones); class is abstract or an interface; constructor throws an exception during init (e.g. reading missing config); inner class without the outer instance; constructor not public.

Related errors

• Class not found
• Class must implement RunListenerFactory or RunListener
• is not a constructor
• Failed to deserialize JSON to
• boot.ext(' '): failed to construct

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

Appendix: source

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

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

        /**
         * Add multiple result listeners.
         */

View on GitHub (pinned to a22eb90246)