karatelabs/karate · error · RuntimeException

HTTP endpoint not available

Error message

HTTP endpoint not available: {url}

What it means

After polling the HTTP endpoint for the full timeout (default 30s) without ever receiving a 2xx/3xx response, karate.waitForHttp() gives up and throws this error naming the URL. It signals the endpoint never became available during the wait window.

Solutions

1. Verify the URL/host/port is correct and the service actually listens there
2. Increase the timeout via the options map, e.g. { timeoutMs: 120000 }
3. Check application startup logs for crashes or slow initialization
4. Confirm the endpoint returns 2xx/3xx (4xx/5xx responses are not treated as success)

Example fix

// before
karate.waitForHttp('http://localhost:8080/health');
// after
karate.waitForHttp('http://localhost:8080/health', { timeoutMs: 120000, pollMs: 500 });

// Pre-check the endpoint manually before committing to a long wait
curl -s -o /dev/null -w '%{http_code}' http://localhost:8080/health

try {
    karate.waitForHttp(url, { timeoutMs: 60000 });
} catch (Exception e) {
    karate.logger.error('endpoint {} never became ready — check service logs', url);
    throw e;
}

When it happens

Trigger: karate.waitForHttp(url) where the server never starts, listens on a different host/port, returns only 4xx/5xx, or the timeout (configurable via the second Map argument) is too short for a slow service.

Common situations: Docker compose services not yet up during integration tests; wrong port in the health URL; app crashing on startup; CI runners with slow cold starts exceeding the 30s default.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Port : not available within timeout
• retry failed after attempts:
• HTTP not available after attempts
• waitForHttp() needs a URL argument
• listen timed out after

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

Appendix: source

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

                            .timeout(Duration.ofMillis(pollMs))
                            .GET()
                            .build();
                    var response = httpClient.send(request, java.net.http.HttpResponse.BodyHandlers.discarding());
                    int status = response.statusCode();
                    if (status >= 200 && status < 400) {
                        return true;
                    }
                } catch (Exception e) {
                    // Connection failed, continue polling
                }
                try {
                    Thread.sleep(pollMs);
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    return false;
                }
            }
            throw new RuntimeException("HTTP endpoint not available: " + url);
        };
    }

    /**
     * karate.waitForPort(host, port) - Wait for a TCP port to become available.
     * Polls until a TCP connection can be established.
     */
    static JavaInvokable waitForPort() {
        return args -> {
            if (args.length < 2) {
                throw new RuntimeException("waitForPort() needs host and port arguments");
            }
            String host = args[0] + "";
            int port;
            if (args[1] instanceof Number) {
                port = ((Number) args[1]).intValue();
            } else {
                port = Integer.parseInt(args[1].toString());

View on GitHub (pinned to a22eb90246)