karatelabs/karate · error · RuntimeException

failed to start debug server

Error message

failed to start debug server

What it means

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.

Solutions

  1. Check the wrapped cause exception (RuntimeException.getCause()) to see the real startup failure and fix it.
  2. Align karate-core and karate-ide versions in your dependency management so the reflective main-class call matches.
  3. If you do not need debugging, remove the -Dkarate.debug.port system property to skip debug-server startup entirely.
  4. 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).

Example fix

// before (maven, mismatched versions)
<dependency><groupId>io.karatelabs</groupId><artifactId>karate-core</artifactId><version>2.0.0</version></dependency>
<dependency><groupId>io.karatelabs</groupId><artifactId>karate-ide</artifactId><version>1.4.0</version></dependency>

// after (versions aligned, or drop debug port)
<dependency><groupId>io.karatelabs</groupId><artifactId>karate-ide</artifactId><version>2.0.0</version></dependency>
<!-- run without -Dkarate.debug.port when not debugging -->
Defensive patterns

Strategy: try-catch

Validate before calling

// before launching
String port = System.getProperty("karate.debug.port");
if (port != null) {
    try { Class.forName("io.karatelabs.ide.Main"); } // debug main class
    catch (ClassNotFoundException e) { System.clearProperty("karate.debug.port"); }
}

Type guard

boolean debugServerAvailable() {
    try { Class.forName("io.karatelabs.ide.Main"); return true; }
    catch (ClassNotFoundException e) { return false; }
}

Try / catch

try {
    suiteResult = runner.run(args);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("failed to start debug server")) {
        logger.warn("debug server unavailable, continuing without debugger", e.getCause());
        suiteResult = runWithoutDebug(args);
    } else { throw e; }
}

Prevention

When it happens

Trigger: 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()).

Common situations: 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.

Related errors

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

Appendix: source

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

                debugPort = Integer.parseInt(debugPortStr.trim());
            } catch (Exception e) {
                // ignore, use 0 (auto-assign)
            }
            // Apply system properties if configured
            if (systemProperties != null) {
                systemProperties.forEach(System::setProperty);
            }
            String[] args = buildDebugArgs(debugPort, threadCount);
            logger.debug("karate.debug.port detected, delegating to debug server: {}", Arrays.toString(args));
            try {
                Class<?> mainClass = Class.forName("io.karatelabs.debug.Main");
                Method runMethod = mainClass.getMethod("run", String[].class);
                return (SuiteResult) runMethod.invoke(null, (Object) args);
            } catch (ClassNotFoundException e) {
                logger.warn("karate.debug.port is set but karate-ide JAR is not on the classpath");
                return null;
            } catch (Exception e) {
                throw new RuntimeException("failed to start debug server", e);
            }
        }

        private String[] buildDebugArgs(int debugPort, int threadCount) {
            List<String> args = new ArrayList<>();
            args.add("-d");
            args.add(String.valueOf(debugPort));
            if (env != null) {
                args.add("-e");
                args.add(env);
            }
            if (tags != null) {
                for (String tag : tags) {
                    args.add("-t");
                    args.add(tag);
                }
            }
            if (threadCount > 1) {

View on GitHub (pinned to a22eb90246)