karatelabs/karate · error · RuntimeException

Port : not available within timeout

Error message

Port {host}:{port} not available within timeout

What it means

karate.waitForPort(host, port) polls for a TCP connection until the timeout expires; if a connection is never established it throws this error naming the host:port. It means the TCP endpoint was unreachable for the entire wait window.

Solutions

1. Confirm the host and port are correct and reachable (telnet/nc test)
2. Increase the wait timeout via the options map argument
3. Check the target service logs — it may have crashed or bound to a different interface (e.g. 127.0.0.1 vs 0.0.0.0)
4. Verify firewall/security-group rules allow the connection

Example fix

// before
karate.waitForPort('db', 5432);
// after
karate.waitForPort('db', 5432, { timeoutMs: 120000 });

// Verify reachability with nc before the wait fails late
nc -z -w 2 <host> <port> && echo open || echo closed

try {
    karate.waitForPort(host, port, { timeoutMs: 120000 });
} catch (Exception e) {
    karate.logger.error('port {}:{} unreachable — is the service up and bound?', [host, port]);
    throw e;
}

When it happens

Trigger: karate.waitForPort(host, port) where the target never opens the port: service not started, wrong host/port, firewall dropping packets, or timeout too short for a slow startup.

Common situations: Waiting for Kafka/DB containers that fail to boot; connecting to 'localhost' from inside a container when the service runs elsewhere; security groups blocking the port in cloud CI.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

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

Related errors

• HTTP endpoint not available
• Timeout waiting for WebDriver on
• waitForPort() needs host and port arguments
• listen timed out after
• retry failed after attempts:

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

Appendix: source

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

            if (args.length > 3 && args[3] instanceof Number) {
                pollMs = ((Number) args[3]).intValue();
            }
            long deadline = System.currentTimeMillis() + timeoutMs;
            while (System.currentTimeMillis() < deadline) {
                try (Socket socket = new Socket(host, port)) {
                    // Port is open, success
                    return true;
                } catch (Exception e) {
                    // Port not available, continue polling
                }
                try {
                    Thread.sleep(pollMs);
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    return false;
                }
            }
            throw new RuntimeException("Port " + host + ":" + port + " not available within timeout");
        };
    }

}

View on GitHub (pinned to a22eb90246)