karatelabs/karate · error · RuntimeException

stop() failed

Error message

stop() failed: {message}

What it means

karate.stop() pauses the test (waiting for a socket/enter signal) and wraps any exception during that wait in 'stop() failed: <message>'. It means the stop/wait mechanism itself errored — e.g. the internal server socket could not be created, bound, or awaited.

Solutions

  1. Check the nested cause message for the underlying socket/IO problem
  2. Verify no other process holds the stop-port (lsof/netstat) and free it
  3. Avoid karate.stop() in CI; guard it with an env check so it only runs during local debugging

Example fix

// before
karate.stop();
// after
if (karate.get('env') == 'local') karate.stop();
Defensive patterns

Strategy: try-catch

Validate before calling

// Check a local port is bindable before stopping
if (karate.env != 'local') karate.logger.info('skipping karate.stop() in non-local env');

Try / catch

try {
    karate.stop();
} catch (Exception e) {
    karate.logger.warn('stop failed (continuing): {}', e.getMessage());
}

Prevention

When it happens

Trigger: Calling karate.stop() when the internal listening socket cannot be opened (port in use, permissions) or the wait is interrupted/fails mid-flight.

Common situations: Running karate.stop() in CI where the pause port is blocked by firewall or another process holds the port; restricted containers disallowing socket binds.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateJsUtils.java:1044

                    port = Integer.parseInt(args[0].toString());
                }
            }
            try (java.net.ServerSocket serverSocket = new java.net.ServerSocket(port, 1,
                    java.net.InetAddress.getByName("127.0.0.1"))) {
                int actualPort = serverSocket.getLocalPort();
                System.out.println("*** waiting for socket, type the command below:\ncurl http://localhost:"
                        + actualPort + "\nin a new terminal (or open the URL in a web-browser) to proceed ...");
                // Block until a connection is received
                try (Socket clientSocket = serverSocket.accept()) {
                    // Send a simple HTTP response
                    java.io.OutputStream out = clientSocket.getOutputStream();
                    out.write("HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK".getBytes());
                    out.flush();
                }
                logger.info("*** exited socket wait successfully");
                return true;
            } catch (Exception e) {
                throw new RuntimeException("stop() failed: " + e.getMessage(), e);
            }
        };
    }

    // ========== Wait Utilities ==========

    /**
     * karate.waitForHttp(url) - Wait for an HTTP endpoint to become available.
     * Polls until a successful response (2xx or 3xx) is received.
     */
    static JavaInvokable waitForHttp() {
        return args -> {
            if (args.length == 0) {
                throw new RuntimeException("waitForHttp() needs a URL argument");
            }
            String url = args[0] + "";
            int timeoutMs = 30000;
            int pollMs = 250;

View on GitHub (pinned to a22eb90246)