karatelabs/karate · error · RuntimeException

cannot find [

Error message

cannot find [

What it means

karate.channel(type) first checks factories registered on the Suite, then falls back to the naming convention io.karatelabs.ext.<Type>.<Type>ChannelFactory loaded reflectively. When the class cannot be found, this rich error explains that no factory is registered and the protocol's leaf jar (e.g. karate-kafka) is not on the classpath, and lists the concrete fixes.

Solutions

  1. Add the protocol dependency to the build: e.g. io.karatelabs:karate-kafka (matching your Karate version)
  2. If running a packaged engine jar, use one that bundles the protocol leaf or place the leaf jar on the classpath
  3. Register a custom ChannelFactory on the Suite at boot (Suite#registerChannelFactory) for custom protocols
  4. Verify the type string exactly matches the module/factory name (case-sensitive first letter is capitalized for the class lookup).

Example fix

// before (pom.xml) — no leaf dependency
<dependency><groupId>io.karatelabs</groupId><artifactId>karate-core</artifactId></dependency>
// after
<dependency><groupId>io.karatelabs</groupId><artifactId>karate-core</artifactId></dependency>
<dependency><groupId>io.karatelabs</groupId><artifactId>karate-kafka</artifactId><version>${karate.version}</version></dependency>
Defensive patterns

Strategy: try-catch

Validate before calling

// build check: ensure the leaf jar exists on the classpath before running
// mvn dependency:tree | grep karate-kafka

Try / catch

try { var ch = karate.channel('kafka'); } catch (e) { if (String(e).indexOf('cannot find [') >= 0) karate.warn('add the karate-<type> dependency or leaf jar to the classpath'); throw e; }

Prevention

When it happens

Trigger: karate.channel('kafka') (or any protocol type) when the karate-<type> module/extension jar is absent from the runtime classpath and no factory was registered via Suite#registerChannelFactory; running a slim/packaged engine jar without bundled protocol leaves; a typo'd type name that matches no factory or class.

Common situations: Maven/Gradle project missing the karate-kafka / karate-grpc style dependency; custom distribution built without protocol modules; running inside a repackaged engine where editing a build file is not an option and the leaf jar must be bundled; spelling the type differently from the module name.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateJs.java:1231

                    // mirroring boot.ext: channel('grpc') -> io.karatelabs.ext.grpc.GrpcChannelFactory.
                    String cap = Character.toUpperCase(type.charAt(0)) + type.substring(1);
                    String factoryClass = "io.karatelabs.ext." + type + "." + cap + "ChannelFactory";
                    Class<?> clazz = Class.forName(factoryClass);
                    factory = (ChannelFactory) clazz.getDeclaredConstructor().newInstance();
                }
                // Channels self-configure via their rich JS object, not via global config.
                Channel channel = factory.create(rt, new HashMap<>());
                rt.registerChannel(channel);
                return channel.init(rt);
            } catch (RuntimeException re) {
                throw re;
            } catch (ClassNotFoundException e) {
                // Name every way the leaf actually arrives. "is it a maven / gradle dependency?" is only
                // one of them, and it is the wrong question for a run inside a packaged engine — where
                // the answer is to run (or add) the jar that carries the leaf, not to edit a build file
                // that is not there. A message that names a fix nobody in that context can perform reads
                // as "this capability is broken".
                throw new RuntimeException("cannot find [" + type + "]: no channel factory is registered for"
                        + " it and io.karatelabs.ext." + type + "." + Character.toUpperCase(type.charAt(0))
                        + type.substring(1) + "ChannelFactory is not on the classpath. Add the 'karate-"
                        + type + "' dependency (maven / gradle), or run an engine jar that bundles the"
                        + " protocol leaves, or put the leaf jar on the classpath.");
            } catch (Exception e) {
                throw new RuntimeException(e.getMessage(), e);
            }
        };
    }

    @Override
    public Object jsGet(String key) {
        return switch (key) {
            // Stateless utility methods (KarateJsApi)
            case "append" -> KarateJsUtils.append();
            case "appendTo" -> KarateJsUtils.appendTo();
            case "distinct" -> KarateJsUtils.distinct();
            case "extract" -> KarateJsUtils.extract();

View on GitHub (pinned to a22eb90246)