{"record":{"id":"0fd51383791abac2","repo":"junit-team/junit5","slug":"failed-to-connect-to-socket-on-port-s","errorCode":null,"errorMessage":"Failed to connect to socket on port %s","messagePattern":"Failed to connect to socket on port (.+?)","errorType":"exception","errorClass":"JUnitException","httpStatus":null,"severity":"error","filePath":"junit-platform-reporting/src/main/java/org/junit/platform/reporting/open/xml/OpenTestReportGeneratingListener.java","lineNumber":158,"sourceCode":"\t\t\t\treportInfrastructure(config);\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new JUnitException(\"Failed to initialize XML events writer\", e);\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate DocumentWriter<Events> createDocumentWriter(ConfigurationParameters config,\n\t\t\tNamespaceRegistry namespaceRegistry) throws Exception {\n\t\treturn config.get(SOCKET_PROPERTY_NAME, Integer::valueOf) //\n\t\t\t\t.map(port -> {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tSocket socket = new Socket(InetAddress.getLoopbackAddress(), port);\n\t\t\t\t\t\tWriter writer = new OutputStreamWriter(socket.getOutputStream(), StandardCharsets.UTF_8);\n\t\t\t\t\t\treturn Events.createDocumentWriter(namespaceRegistry, writer);\n\t\t\t\t\t}\n\t\t\t\t\tcatch (Exception e) {\n\t\t\t\t\t\tthrow new JUnitException(\"Failed to connect to socket on port \" + port, e);\n\t\t\t\t\t}\n\t\t\t\t}) //\n\t\t\t\t.orElseGet(() -> {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tPath eventsXml = requireNonNull(outputDir).resolve(\"open-test-report.xml\");\n\t\t\t\t\t\treturn Events.createDocumentWriter(namespaceRegistry, eventsXml);\n\t\t\t\t\t}\n\t\t\t\t\tcatch (Exception e) {\n\t\t\t\t\t\tthrow new JUnitException(\"Failed to create XML events file\", e);\n\t\t\t\t\t}\n\t\t\t\t});\n\t}\n\n\tprivate boolean isEnabled(ConfigurationParameters config) {\n\t\treturn config.getBoolean(ENABLED_PROPERTY_NAME).orElse(false);\n\t}\n\n\tprivate boolean isGitEnabled(ConfigurationParameters config) {","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/junit-team/junit5/blob/f070c699a08b5d8393df9afd147af5c5e90bb21b/junit-platform-reporting/src/main/java/org/junit/platform/reporting/open/xml/OpenTestReportGeneratingListener.java#L140-L176","documentation":"Thrown as a JUnitException by OpenTestReportGeneratingListener.createDocumentWriter() when connecting a loopback TCP socket to the port configured via 'junit.platform.reporting.open.xml.socket' fails. The listener only takes the socket branch when that property is set to an integer; otherwise it falls back to writing a file. The connection is always to InetAddress.getLoopbackAddress() (127.0.0.1), so remote/firewall issues are usually not the cause. This exception is normally caught and re-wrapped as error 145.","triggerScenarios":"Setting junit.platform.reporting.open.xml.socket=<port> when no process is listening on 127.0.0.1 at that port; the consumer server died before the test run started; the port number is wrong or already reused by an unrelated service that rejects the connection; the OS refused the loopback connection (exhausted ephemeral ports).","commonSituations":"IDE/test-tool integrations that spawn a socket server to ingest events but fail to start it; port typo in CI config; the server bound to a non-loopback interface; the consumer crashed and the port is not yet in TIME-WAIT clear state.","solutions":["Start the socket consumer and confirm it listens on 127.0.0.1:<port> before launching the test JVM.","Remove the junit.platform.reporting.open.xml.socket property to fall back to file-based output (open-test-report.xml).","Verify the port number matches between the consumer and the -D flag.","Ensure the consumer binds to the loopback interface specifically, since the listener hard-codes InetAddress.getLoopbackAddress()."],"exampleFix":"// before\n-Djunit.platform.reporting.open.xml.socket=9999  // (no server listening)\n\n// after\n// remove the property, or start the server first on 127.0.0.1:9999","handlingStrategy":"validation","validationCode":"// If the socket transport is requested, probe loopback reachability before the run.\nString portProp = System.getProperty(\"junit.platform.reporting.open.xml.socket\");\nif (portProp != null) {\n    int port = Integer.parseInt(portProp);\n    try (Socket probe = new Socket()) {\n        probe.connect(new InetSocketAddress(InetAddress.getLoopbackAddress(), port), 1000);\n    } catch (IOException e) {\n        System.clearProperty(\"junit.platform.reporting.open.xml.socket\");\n        // falls back to file-based open-test-report.xml\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    launcher.execute(request);\n} catch (JUnitException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to connect to socket on port\")) {\n        // Consumer not running; clear the socket property and retry with file output.\n    } else {\n        throw e;\n    }\n}","preventionTips":["Start the socket consumer on 127.0.0.1 before launching the test JVM.","Remember the listener always connects to InetAddress.getLoopbackAddress(); the server must bind to loopback.","Prefer file output unless a live consumer is guaranteed for the whole run.","Verify the port number is free and matches on both sides."],"tags":["network","socket","reporting","configuration","loopback"],"backgroundTag":null,"analyzedSha":"f070c699a08b5d8393df9afd147af5c5e90bb21b","analyzedAt":"2026-08-11T20:31:00.530Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}