{"record":{"id":"ea3643dacf8135e0","repo":"karatelabs/karate","slug":"stop-failed-message","errorCode":null,"errorMessage":"stop() failed: {message}","messagePattern":"stop\\(\\) failed: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/KarateJsUtils.java","lineNumber":1044,"sourceCode":"                    port = Integer.parseInt(args[0].toString());\n                }\n            }\n            try (java.net.ServerSocket serverSocket = new java.net.ServerSocket(port, 1,\n                    java.net.InetAddress.getByName(\"127.0.0.1\"))) {\n                int actualPort = serverSocket.getLocalPort();\n                System.out.println(\"*** waiting for socket, type the command below:\\ncurl http://localhost:\"\n                        + actualPort + \"\\nin a new terminal (or open the URL in a web-browser) to proceed ...\");\n                // Block until a connection is received\n                try (Socket clientSocket = serverSocket.accept()) {\n                    // Send a simple HTTP response\n                    java.io.OutputStream out = clientSocket.getOutputStream();\n                    out.write(\"HTTP/1.1 200 OK\\r\\nContent-Length: 2\\r\\n\\r\\nOK\".getBytes());\n                    out.flush();\n                }\n                logger.info(\"*** exited socket wait successfully\");\n                return true;\n            } catch (Exception e) {\n                throw new RuntimeException(\"stop() failed: \" + e.getMessage(), e);\n            }\n        };\n    }\n\n    // ========== Wait Utilities ==========\n\n    /**\n     * karate.waitForHttp(url) - Wait for an HTTP endpoint to become available.\n     * Polls until a successful response (2xx or 3xx) is received.\n     */\n    static JavaInvokable waitForHttp() {\n        return args -> {\n            if (args.length == 0) {\n                throw new RuntimeException(\"waitForHttp() needs a URL argument\");\n            }\n            String url = args[0] + \"\";\n            int timeoutMs = 30000;\n            int pollMs = 250;","sourceCodeStart":1026,"sourceCodeEnd":1062,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/KarateJsUtils.java#L1026-L1062","documentation":"karate.stop() pauses the test (waiting for a socket/enter signal) and wraps any exception during that wait in 'stop() failed: <message>'. It means the stop/wait mechanism itself errored — e.g. the internal server socket could not be created, bound, or awaited.","triggerScenarios":"Calling karate.stop() when the internal listening socket cannot be opened (port in use, permissions) or the wait is interrupted/fails mid-flight.","commonSituations":"Running karate.stop() in CI where the pause port is blocked by firewall or another process holds the port; restricted containers disallowing socket binds.","solutions":["Check the nested cause message for the underlying socket/IO problem","Verify no other process holds the stop-port (lsof/netstat) and free it","Avoid karate.stop() in CI; guard it with an env check so it only runs during local debugging"],"exampleFix":"// before\nkarate.stop();\n// after\nif (karate.get('env') == 'local') karate.stop();","handlingStrategy":"try-catch","validationCode":"// Check a local port is bindable before stopping\nif (karate.env != 'local') karate.logger.info('skipping karate.stop() in non-local env');","typeGuard":null,"tryCatchPattern":"try {\n    karate.stop();\n} catch (Exception e) {\n    karate.logger.warn('stop failed (continuing): {}', e.getMessage());\n}","preventionTips":["Never call karate.stop() in CI pipelines — guard on karate.env","Ensure the debug port is free before running","Read the nested cause to identify socket bind problems"],"tags":["socket","debugging","pause"],"backgroundTag":"address-already-in-use","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"}