{"record":{"id":"8f51d9d4df32f1f0","repo":"karatelabs/karate","slug":"java-bridge-not-enabled","errorCode":null,"errorMessage":"java bridge not enabled","messagePattern":"java bridge not enabled","errorType":"exception","errorClass":"java.lang.RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-js/src/main/java/io/karatelabs/js/JsJava.java","lineNumber":32,"sourceCode":" * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\n * THE SOFTWARE.\n */\npackage io.karatelabs.js;\n\npublic class JsJava implements SimpleObject {\n\n    final ExternalBridge bridge;\n\n    JsJava(ExternalBridge bridge) {\n        if (bridge == null) {\n            throw new RuntimeException(\"java bridge not enabled\");\n        }\n        this.bridge = bridge;\n    }\n\n    @Override\n    public Object jsGet(String name) {\n        return switch (name) {\n            case \"type\" -> (JsInvokable) args -> {\n                String className = (String) args[0];\n                // forType() returns null on ClassNotFoundException — that\n                // null-as-sentinel contract is needed by PropertyAccess for\n                // the dotted-FQN probe, so we keep it. But here the script\n                // explicitly asked for this class; a null result must surface\n                // as a real error rather than silently propagating and\n                // failing later as \"cannot read properties of null\".\n                ExternalAccess type = bridge.forType(className);\n                if (type == null) {\n                    throw JsErrorException.typeError(\"Java.type: class not found: \" + className);","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-js/src/main/java/io/karatelabs/js/JsJava.java#L14-L50","documentation":"The JsJava wrapper (the `Java` interop object) is constructed with a null ExternalBridge, meaning the JS engine was created without Java-bridge support enabled. The library throws immediately rather than failing later on first Java call, so misconfiguration is detected at setup time.","triggerScenarios":"Creating a JS Context/engine without registering an ExternalBridge (or with bridge disabled) and then referencing the `Java` global, e.g. Java.type(...).","commonSituations":"Embedding karate-js standalone (outside Karate's runtime) without wiring the Java bridge; running in a mode where Java interop is intentionally disabled (sandboxed scripts); forgetting the builder flag that enables interop after an upgrade.","solutions":["Enable the Java bridge when building the engine/context (pass an ExternalBridge to the builder).","If interop should be unavailable, don't reference the `Java` global in scripts; gate such code behind a capability check.","Check the engine-construction code path for a null/omitted bridge argument.","If embedding via Karate, use the standard runtime entry points that wire the bridge automatically."],"exampleFix":"// before\nContext ctx = Context.forRoot(); // no bridge => Java global unusable\n// after\nContext ctx = Context.newBuilder().externalBridge(myBridge).build();","handlingStrategy":"validation","validationCode":"if (bridge == null) throw new IllegalStateException(\"enable the Java bridge before using the Java global\"); // or check at engine build time\nContext ctx = Context.newBuilder().externalBridge(bridge).build();","typeGuard":"boolean javaInteropAvailable(Context ctx) { return ctx != null && ctx.getExternalBridge() != null; }","tryCatchPattern":"try { var t = Java.type(\"com.example.Foo\"); } catch (RuntimeException e) { if (String(e.message).includes(\"java bridge not enabled\")) { /* fall back or surface config error */ } else throw e; }","preventionTips":["Wire the ExternalBridge in one shared engine-factory method so it can't be forgotten.","Document/sandbox scripts that must not use Java interop and assert the bridge is intentionally absent there.","Fail fast at startup with an explicit config check rather than at first Java.type call.","After upgrades, re-verify builder flags that toggle interop."],"tags":["javascript","java-interop","configuration"],"backgroundTag":"feature-not-enabled","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"}