karatelabs/karate · error · IllegalArgumentException

port must be between 1 and 65535

Error message

port must be between 1 and 65535

What it means

getWebSocketUrl(host, port) validates the DevTools port range before making an HTTP request to http://host:port. Ports outside 1-65535 are invalid, so an IllegalArgumentException is thrown up front instead of a confusing network failure later.

Solutions

1. Pass a real DevTools port in 1-65535, or resolve one first with PortUtils.findFreePort()
2. Validate/normalize the port value at the call site before calling getWebSocketUrl
3. If the port was configured as 0 meaning 'auto', use CdpLauncher.start(options) instead, which picks a free port itself

Example fix

// before
String url = CdpLauncher.getWebSocketUrl("localhost", 0);
// after
int port = PortUtils.findFreePort();
String url = CdpLauncher.getWebSocketUrl("localhost", port);

if (port < 1 || port > 65535) {
    port = PortUtils.findFreePort();
}
CdpLauncher.getWebSocketUrl(host, port);

Integer validPort(Integer p) {
    return (p != null && p >= 1 && p <= 65535) ? p : PortUtils.findFreePort();
}

try {
    CdpLauncher.getWebSocketUrl(host, port);
} catch (IllegalArgumentException e) {
    // resolve a real port and retry
    CdpLauncher.getWebSocketUrl(host, PortUtils.findFreePort());
}

When it happens

Trigger: Calling CdpLauncher.getWebSocketUrl(host, 0), a negative port, or a port above 65535; passing an uninitialized port variable that defaulted to 0.

Common situations: Port field defaulting to 0 ('auto') and then passed directly to this API; parsing a port string incorrectly; mixing up a local socket port with an unrelated numeric setting.

Related errors

• embed(): each 'parts' entry must be an object
• embed(): each part needs a 'role'
• embed(): part ' ' needs 'data', 'path', or 'url
• Invalid config: expected JSON object
• ReportAssets.named: name is null or empty

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

Appendix: source

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

        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);
    }

    private static String resolveExecutable(String configured) {
        if (configured != null && !configured.isEmpty()) {
            if (Files.isExecutable(Path.of(configured))) {
                return configured;
            }
            logger.warn("configured executable not found: {}", configured);
        }

        String defaultPath = getDefaultPath();
        if (defaultPath != null && Files.isExecutable(Path.of(defaultPath))) {
            logger.debug("using default chrome path: {}", defaultPath);
            return defaultPath;
        }

View on GitHub (pinned to a22eb90246)