karate.debug.port is set but karate-ide JAR is not on the…

Error message

karate.debug.port is set but karate-ide JAR is not on the classpath

What it means

The runner detected karate.debug.port in the system properties, which requests starting the debug/DAP server, but the optional karate-ide JAR containing io.karatelabs.debug.Main is not on the classpath. The runner logs this warning and returns null (proceeds as if debug mode was not requested) instead of failing the run.

Solutions

Add the karate-ide JAR/artifact to the classpath (Maven/Gradle dependency or -cp entry).
Remove the karate.debug.port system property if debug mode was not intended.
Verify the debug Main class is present: Class.forName("io.karatelabs.debug.Main") should succeed.
If launched from an IDE, ensure the debug run configuration includes the karate-ide module on the runtime classpath.

Example fix

// before (pom.xml)
<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-ide</artifactId></dependency>

Defensive patterns

Strategy: fallback

Validate before calling

try { Class.forName("io.karatelabs.debug.Main"); } catch (ClassNotFoundException e) { /* karate-ide missing: unset karate.debug.port or add dependency */ }

Prevention

Declare karate-ide as a test-scope dependency wherever debug mode is used.
Don't set karate.debug.port in shared CI configs or JVM defaults.
Check classpath for the debug Main class in custom launch scripts.

When it happens

Trigger: Setting -Dkarate.debug.port (or the equivalent option) while running Runner via Builder.path/features without the karate-ide artifact as a dependency.

Common situations: IDE plugins expecting the debug server; CI runs that inherit a debug-port JVM flag; upgrading to a modular build where karate-ide became an optional dependency.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

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

Appendix: source

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

            }
            int debugPort = 0;
            try {
                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);

View on GitHub (pinned to a22eb90246)