{"record":{"id":"f9217afadde4eb27","repo":"karatelabs/karate","slug":"process-died-while-waiting-for-port","errorCode":null,"errorMessage":"process died while waiting for port {}:{}","messagePattern":"process died while waiting for port (.+?):(.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"karate-core/src/main/java/io/karatelabs/process/PortUtils.java","lineNumber":62,"sourceCode":"    private static final Logger logger = LoggerFactory.getLogger(\"karate.runtime\");\n\n    private PortUtils() {\n    }\n\n    /**\n     * Wait for a TCP port to become available.\n     *\n     * @param host       Host to connect to\n     * @param port       Port number\n     * @param attempts   Maximum number of attempts\n     * @param intervalMs Interval between attempts in milliseconds\n     * @param stillAlive Supplier that returns false if we should stop waiting (e.g., process died)\n     * @return true if port is available, false if timed out or process died\n     */\n    public static boolean waitForPort(String host, int port, int attempts, int intervalMs, BooleanSupplier stillAlive) {\n        for (int i = 0; i < attempts; i++) {\n            if (stillAlive != null && !stillAlive.getAsBoolean()) {\n                logger.warn(\"process died while waiting for port {}:{}\", host, port);\n                return false;\n            }\n            try (Socket socket = new Socket()) {\n                socket.connect(new InetSocketAddress(host, port), 1000);\n                logger.debug(\"port {}:{} is available after {} attempts\", host, port, i + 1);\n                return true;\n            } catch (Exception e) {\n                logger.trace(\"port {}:{} not yet available (attempt {})\", host, port, i + 1);\n                sleep(intervalMs);\n            }\n        }\n        logger.warn(\"port {}:{} not available after {} attempts\", host, port, attempts);\n        return false;\n    }\n\n    /**\n     * Wait for an HTTP endpoint to return 200.\n     */","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/process/PortUtils.java#L44-L80","documentation":"`PortUtils.waitForPort` polls a host:port until it accepts connections, but between attempts it checks the `stillAlive` supplier. If the supplier reports the watched process has died, waiting is abandoned and this warning is logged; the method returns false. This avoids waiting out the full timeout for a process that can never open the port.","triggerScenarios":"Starting a child process (e.g. a mock server or app under test) and calling `waitForPort(host, port, attempts, intervalMs, process::isAlive)`; the process exits (crash, bad main class, port bind failure) before the port ever opens.","commonSituations":"Application under test failing to start due to a missing dependency or bad config; port already bound by another process causing immediate exit; JVM crash during startup; wrong start command in CI.","solutions":["Inspect the process stdout/stderr for the real startup failure before the exit","Verify the start command, working directory, and classpath/main class","Check that the target port is not already in use by another process","Increase the process's startup resources or fix its configuration, then retry"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if (!PortUtils.waitForPort(host, port, 60, 500, proc::isAlive)) {\n    // process died: dump proc.output() / exit code and fail fast with that context\n    throw new RuntimeException(\"process exited before opening port \" + port);\n}","preventionTips":["Always pass a stillAlive supplier so death is detected early","Capture and check child process stdout/stderr on startup","Validate the start command and port availability before launching","Use generous but bounded attempts/interval for slow services"],"tags":["process","port","startup","lifecycle"],"backgroundTag":"process-exited-unexpectedly","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"}