What causes "process died while waiting for port {}:{}" in karatelabs/karate?

Inspect the process stdout/stderr for the real startup failure before the exit

process died while waiting for port

Error message

process died while waiting for port {}:{}

What it means

`PortUtils.waitForPort` polls a host:port until it accepts connections, but between attempts it checks the `stillAlive` supplier. If the supplier reports the watched process has died, waiting is abandoned and this warning is logged; the method returns false. This avoids waiting out the full timeout for a process that can never open the port.

Solutions

Inspect the process stdout/stderr for the real startup failure before the exit
Verify the start command, working directory, and classpath/main class
Check that the target port is not already in use by another process
Increase the process's startup resources or fix its configuration, then retry

Defensive patterns

Strategy: retry

Try / catch

if (!PortUtils.waitForPort(host, port, 60, 500, proc::isAlive)) {
    // process died: dump proc.output() / exit code and fail fast with that context
    throw new RuntimeException("process exited before opening port " + port);
}

Prevention

Always pass a stillAlive supplier so death is detected early
Capture and check child process stdout/stderr on startup
Validate the start command and port availability before launching
Use generous but bounded attempts/interval for slow services

When it happens

Trigger: Starting a child process (e.g. a mock server or app under test) and calling `waitForPort(host, port, attempts, intervalMs, process::isAlive)`; the process exits (crash, bad main class, port bind failure) before the port ever opens.

Common situations: Application under test failing to start due to a missing dependency or bad config; port already bound by another process causing immediate exit; JVM crash during startup; wrong start command in CI.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/process/PortUtils.java:62

    private static final Logger logger = LoggerFactory.getLogger("karate.runtime");

    private PortUtils() {
    }

    /**
     * Wait for a TCP port to become available.
     *
     * @param host       Host to connect to
     * @param port       Port number
     * @param attempts   Maximum number of attempts
     * @param intervalMs Interval between attempts in milliseconds
     * @param stillAlive Supplier that returns false if we should stop waiting (e.g., process died)
     * @return true if port is available, false if timed out or process died
     */
    public static boolean waitForPort(String host, int port, int attempts, int intervalMs, BooleanSupplier stillAlive) {
        for (int i = 0; i < attempts; i++) {
            if (stillAlive != null && !stillAlive.getAsBoolean()) {
                logger.warn("process died while waiting for port {}:{}", host, port);
                return false;
            }
            try (Socket socket = new Socket()) {
                socket.connect(new InetSocketAddress(host, port), 1000);
                logger.debug("port {}:{} is available after {} attempts", host, port, i + 1);
                return true;
            } catch (Exception e) {
                logger.trace("port {}:{} not yet available (attempt {})", host, port, i + 1);
                sleep(intervalMs);
            }
        }
        logger.warn("port {}:{} not available after {} attempts", host, port, attempts);
        return false;
    }

    /**
     * Wait for an HTTP endpoint to return 200.
     */

View on GitHub (pinned to a22eb90246)