{"record":{"id":"1f79a55b32ecf34d","repo":"karatelabs/karate","slug":"failed-to-start-debug-server","errorCode":null,"errorMessage":"failed to start debug server","messagePattern":"failed to start debug server","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/Runner.java","lineNumber":1030,"sourceCode":"                debugPort = Integer.parseInt(debugPortStr.trim());\n            } catch (Exception e) {\n                // ignore, use 0 (auto-assign)\n            }\n            // Apply system properties if configured\n            if (systemProperties != null) {\n                systemProperties.forEach(System::setProperty);\n            }\n            String[] args = buildDebugArgs(debugPort, threadCount);\n            logger.debug(\"karate.debug.port detected, delegating to debug server: {}\", Arrays.toString(args));\n            try {\n                Class<?> mainClass = Class.forName(\"io.karatelabs.debug.Main\");\n                Method runMethod = mainClass.getMethod(\"run\", String[].class);\n                return (SuiteResult) runMethod.invoke(null, (Object) args);\n            } catch (ClassNotFoundException e) {\n                logger.warn(\"karate.debug.port is set but karate-ide JAR is not on the classpath\");\n                return null;\n            } catch (Exception e) {\n                throw new RuntimeException(\"failed to start debug server\", e);\n            }\n        }\n\n        private String[] buildDebugArgs(int debugPort, int threadCount) {\n            List<String> args = new ArrayList<>();\n            args.add(\"-d\");\n            args.add(String.valueOf(debugPort));\n            if (env != null) {\n                args.add(\"-e\");\n                args.add(env);\n            }\n            if (tags != null) {\n                for (String tag : tags) {\n                    args.add(\"-t\");\n                    args.add(tag);\n                }\n            }\n            if (threadCount > 1) {","sourceCodeStart":1012,"sourceCodeEnd":1048,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/Runner.java#L1012-L1048","documentation":"Builder.run() attempts to start the Karate debug server (used by IDE/debug integration) when the karate.debug.port system property is set. It launches the main class from the karate-ide JAR reflectively; any failure other than the JAR simply being absent is rethrown wrapped in this RuntimeException. It signals a broken or misconfigured debug-server classpath/setup, not a normal test failure.","triggerScenarios":"Running Runner/Builder with -Dkarate.debug.port set while the karate-ide JAR is on the classpath but the debug main class is incompatible (wrong version, method signature mismatch) or fails during startup (e.g. port bind error surfaced through the invoked run()).","commonSituations":"Launching Karate from an IDE debugger or a VS Code extension with a karate-core version mismatched against the karate-ide dependency; a stale or conflicting karate-ide JAR; another process already holding the debug port.","solutions":["Check the wrapped cause exception (RuntimeException.getCause()) to see the real startup failure and fix it.","Align karate-core and karate-ide versions in your dependency management so the reflective main-class call matches.","If you do not need debugging, remove the -Dkarate.debug.port system property to skip debug-server startup entirely.","If the message is a class-not-found variant instead, add the karate-ide JAR to the classpath (absence of the JAR alone is only a warning, not this error)."],"exampleFix":"// before (maven, mismatched versions)\n<dependency><groupId>io.karatelabs</groupId><artifactId>karate-core</artifactId><version>2.0.0</version></dependency>\n<dependency><groupId>io.karatelabs</groupId><artifactId>karate-ide</artifactId><version>1.4.0</version></dependency>\n\n// after (versions aligned, or drop debug port)\n<dependency><groupId>io.karatelabs</groupId><artifactId>karate-ide</artifactId><version>2.0.0</version></dependency>\n<!-- run without -Dkarate.debug.port when not debugging -->","handlingStrategy":"try-catch","validationCode":"// before launching\nString port = System.getProperty(\"karate.debug.port\");\nif (port != null) {\n    try { Class.forName(\"io.karatelabs.ide.Main\"); } // debug main class\n    catch (ClassNotFoundException e) { System.clearProperty(\"karate.debug.port\"); }\n}","typeGuard":"boolean debugServerAvailable() {\n    try { Class.forName(\"io.karatelabs.ide.Main\"); return true; }\n    catch (ClassNotFoundException e) { return false; }\n}","tryCatchPattern":"try {\n    suiteResult = runner.run(args);\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"failed to start debug server\")) {\n        logger.warn(\"debug server unavailable, continuing without debugger\", e.getCause());\n        suiteResult = runWithoutDebug(args);\n    } else { throw e; }\n}","preventionTips":["Only set karate.debug.port when karate-ide is on the classpath","Keep karate-core and karate-ide versions identical in dependency management","Read the chained cause (getCause()) to diagnose the real startup failure","Remove stale karate-ide JARs that could shadow incompatible classes"],"tags":["debug-server","classpath","reflection","jvm"],"backgroundTag":"module-init-failed","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"}