{"record":{"id":"d4a1111a5a5fcfab","repo":"karatelabs/karate","slug":"boot-ext-name-not-on-classpath-expected-classname-name","errorCode":null,"errorMessage":"boot.ext('${name}'): not on classpath. Expected ${className} (name-convention resolution).","messagePattern":"boot\\.ext\\('(.+?)'\\): not on classpath\\. Expected (.+?) \\(name-convention resolution\\)\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/BootBinding.java","lineNumber":233,"sourceCode":"        // Singleton-per-name within this BootBinding (which is itself per-Suite).\n        for (Ext existing : exts) {\n            if (name.equals(extShortName(existing))) {\n                return existing;\n            }\n        }\n        String className = extClassName(name);\n        Ext ext;\n        try {\n            Class<?> cls = Class.forName(className);\n            Object instance = cls.getDeclaredConstructor().newInstance();\n            if (!(instance instanceof Ext)) {\n                throw new RuntimeException(\n                        \"boot.ext('\" + name + \"'): \" + className\n                                + \" does not implement io.karatelabs.core.Ext\");\n            }\n            ext = (Ext) instance;\n        } catch (ClassNotFoundException e) {\n            throw new RuntimeException(\n                    \"boot.ext('\" + name + \"'): not on classpath. Expected \"\n                            + className + \" (name-convention resolution).\", e);\n        } catch (Exception e) {\n            throw new RuntimeException(\n                    \"boot.ext('\" + name + \"'): failed to construct \" + className\n                            + \" — \" + e.getMessage(), e);\n        }\n        // Fire onBoot eagerly per K43. Throws here fail the Suite.\n        ext.onBoot(suite);\n        exts.add(ext);\n        registrar.accept(ext);\n        logger.info(\"ext booted: {} ({})\", name, ext.getClass().getName());\n        return ext;\n    }\n\n    /**\n     * {@code boot.has('name')} — is this ext available to boot? A pure classpath probe using the same\n     * name convention as {@link #ext(String)}; constructs nothing and registers nothing.","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/BootBinding.java#L215-L251","documentation":"boot.ext(name) derives a fully-qualified class name from the given short name via naming convention and loads it with Class.forName. When the class is absent from the runtime classpath, a ClassNotFoundException is wrapped in a RuntimeException stating the expected class name so the developer knows exactly what to provide.","triggerScenarios":"boot.ext('myext') where the convention-derived class (e.g. the Ext implementation for 'myext') is not on the test/runtime classpath — extension jar not declared as a dependency, wrong artifact, or class in a source set not compiled into the run.","commonSituations":"Forgot to add the extension Maven/Gradle dependency; extension implemented locally but under a package that doesn't match the name convention; running only the main source set while the ext lives in test sources; typo in the extension name.","solutions":["Add the extension's jar/dependency to the runtime classpath (Maven/Gradle dependency).","Check the derived class name in the message and place your Ext implementation at exactly that fully-qualified name.","Verify the extension module is compiled and included in the runtime source set/test classpath.","Correct typos in the extension short name passed to boot.ext."],"exampleFix":"// before\nboot.ext('myext'); // class not on classpath\n// after (pom.xml)\n<dependency>\n  <groupId>com.example</groupId>\n  <artifactId>karate-ext-myext</artifactId>\n  <version>1.0.0</version>\n</dependency>\n// then boot.ext('myext');","handlingStrategy":"validation","validationCode":"// before boot.ext(name), check the convention-derived class is loadable\ntry {\n    Class.forName(\"io.karatelabs.ext.MyExt\"); // the FQCN the message reports\n} catch (ClassNotFoundException e) {\n    // dependency missing — add the extension artifact before booting\n}","typeGuard":null,"tryCatchPattern":"try {\n    boot.ext(name);\n} catch (RuntimeException e) {\n    // read the expected class name from the message and add the missing dependency\n}","preventionTips":["Declare extension dependencies in the build file of every project that boots them.","Match the implementation's package exactly to the naming convention.","Confirm test vs main source set placement for locally implemented extensions."],"tags":["boot","extension","classpath","dependency"],"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"}