{"record":{"id":"bb51ea77563fa1aa","repo":"karatelabs/karate","slug":"port-host-port-not-available-within-timeout","errorCode":null,"errorMessage":"Port {host}:{port} not available within timeout","messagePattern":"Port (.+?):(.+?) not available within timeout","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/KarateJsUtils.java","lineNumber":1142,"sourceCode":"            if (args.length > 3 && args[3] instanceof Number) {\n                pollMs = ((Number) args[3]).intValue();\n            }\n            long deadline = System.currentTimeMillis() + timeoutMs;\n            while (System.currentTimeMillis() < deadline) {\n                try (Socket socket = new Socket(host, port)) {\n                    // Port is open, success\n                    return true;\n                } catch (Exception e) {\n                    // Port not available, continue polling\n                }\n                try {\n                    Thread.sleep(pollMs);\n                } catch (InterruptedException e) {\n                    Thread.currentThread().interrupt();\n                    return false;\n                }\n            }\n            throw new RuntimeException(\"Port \" + host + \":\" + port + \" not available within timeout\");\n        };\n    }\n\n}\n","sourceCodeStart":1124,"sourceCodeEnd":1147,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/KarateJsUtils.java#L1124-L1147","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the host and port are correct and reachable (telnet/nc test)","Increase the wait timeout via the options map argument","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)","Verify firewall/security-group rules allow the connection"],"exampleFix":"// before\nkarate.waitForPort('db', 5432);\n// after\nkarate.waitForPort('db', 5432, { timeoutMs: 120000 });","handlingStrategy":"retry","validationCode":"// Verify reachability with nc before the wait fails late\nnc -z -w 2 <host> <port> && echo open || echo closed","typeGuard":null,"tryCatchPattern":"try {\n    karate.waitForPort(host, port, { timeoutMs: 120000 });\n} catch (Exception e) {\n    karate.logger.error('port {}:{} unreachable — is the service up and bound?', [host, port]);\n    throw e;\n}","preventionTips":["Increase timeoutMs for slow-starting services (databases, brokers)","Confirm the service binds to an interface reachable from the test (0.0.0.0, not just 127.0.0.1)","Open firewall/security-group rules for the port in CI","Smoke-test with nc/telnet before running the suite"],"tags":["tcp","timeout","connection","polling"],"backgroundTag":"connection-refused","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}