karatelabs/karate · critical · RuntimeException

chrome failed to start or no page targets available within…

Error message

chrome failed to start or no page targets available within timeout (${timeout}ms)

What it means

After spawning the Chrome process, the launcher polls for a DevTools WebSocket URL. If no page target (and thus no WS endpoint) appears within the timeout, Chrome is closed and this RuntimeException is thrown. It signals the browser process either failed to start or started without exposing usable page targets in time.

Solutions

1. Increase the startup timeout in driver options (e.g. timeout setting) and retry
2. Run Chrome manually with the same flags (check karate.log for the command line) to see why it exits
3. In containers, ensure headless mode plus --no-sandbox / adequate /dev/shm size
4. Verify the configured executable actually runs: `<executable> --version`
5. Check for stale Chrome processes or a port conflict and clean them up

Example fix

// before (tight timeout on slow CI)
options.setTimeout(5000);
// after
options.setTimeout(30000);

Process check = new ProcessBuilder(executable, "--version").start();
if (check.waitFor(5, TimeUnit.SECONDS) && check.exitValue() != 0) {
    throw new IllegalStateException("chrome binary broken");
}

try {
    CdpLauncher.start(options);
} catch (RuntimeException e) {
    // chrome not ready in time — retry with larger timeout
    options.setTimeout(options.getTimeout() * 2);
    CdpLauncher.start(options);
}

When it happens

Trigger: Chrome binary exists but crashes on launch (bad flags, missing sandbox permissions, display unavailable); very slow machine where Chrome startup exceeds the timeout; Chrome version whose /json endpoint exposes no page targets within the wait window.

Common situations: CI containers without --no-sandbox or without a running X/display; headless Chrome killed by OOM; overly tight custom timeout in driver options; broken Chrome install that exits immediately.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• HTTP endpoint not available
• Port : not available within timeout
• listen timed out after
• retry failed after attempts:
• Timeout waiting for available driver for scenario

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/cdp/CdpLauncher.java:122

        List<String> args = buildArgs(executable, port, options);
        logger.debug("launching chrome: {}", args);

        ProcessHandle process = ProcessHandle.start(
                ProcessBuilder.create()
                        .args(args)
                        .logToContext(false) // don't log browser output to test context
                        .build()
        );

        CdpLauncher launcher = new CdpLauncher(process, host, port);

        // Wait for Chrome to be ready AND get WebSocket URL atomically
        // This avoids a race condition where /json/version returns 200
        // before any page targets are available
        launcher.webSocketUrl = launcher.waitForWebSocketUrl(timeout);
        if (launcher.webSocketUrl == null) {
            launcher.close();
            throw new RuntimeException("chrome failed to start or no page targets available within timeout (" + timeout + "ms)");
        }

        logger.info("chrome started on port {} with WebSocket: {}", port, launcher.webSocketUrl);
        return launcher;
    }

    /**
     * Get WebSocket URL from existing browser at host:port.
     */
    public static String getWebSocketUrl(String host, int port) {
        if (host == null || host.isEmpty()) {
            host = "localhost";
        }
        if (port <= 0 || port > 65535) {
            throw new IllegalArgumentException("port must be between 1 and 65535");
        }
        return fetchWebSocketUrl(host, port);
    }

View on GitHub (pinned to a22eb90246)