junit-team/junit5 · error · JUnitException

Failed to connect to socket on port %s

Error message

Failed to connect to socket on port %s

What it means

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.

Source

Thrown at junit-platform-reporting/src/main/java/org/junit/platform/reporting/open/xml/OpenTestReportGeneratingListener.java:158

				reportInfrastructure(config);
			}
			catch (Exception e) {
				throw new JUnitException("Failed to initialize XML events writer", e);
			}
		}
	}

	private DocumentWriter<Events> createDocumentWriter(ConfigurationParameters config,
			NamespaceRegistry namespaceRegistry) throws Exception {
		return config.get(SOCKET_PROPERTY_NAME, Integer::valueOf) //
				.map(port -> {
					try {
						Socket socket = new Socket(InetAddress.getLoopbackAddress(), port);
						Writer writer = new OutputStreamWriter(socket.getOutputStream(), StandardCharsets.UTF_8);
						return Events.createDocumentWriter(namespaceRegistry, writer);
					}
					catch (Exception e) {
						throw new JUnitException("Failed to connect to socket on port " + port, e);
					}
				}) //
				.orElseGet(() -> {
					try {
						Path eventsXml = requireNonNull(outputDir).resolve("open-test-report.xml");
						return Events.createDocumentWriter(namespaceRegistry, eventsXml);
					}
					catch (Exception e) {
						throw new JUnitException("Failed to create XML events file", e);
					}
				});
	}

	private boolean isEnabled(ConfigurationParameters config) {
		return config.getBoolean(ENABLED_PROPERTY_NAME).orElse(false);
	}

	private boolean isGitEnabled(ConfigurationParameters config) {

View on GitHub (pinned to f070c699a0)

Solutions

1. Start the socket consumer and confirm it listens on 127.0.0.1:<port> before launching the test JVM.
2. Remove the junit.platform.reporting.open.xml.socket property to fall back to file-based output (open-test-report.xml).
3. Verify the port number matches between the consumer and the -D flag.
4. Ensure the consumer binds to the loopback interface specifically, since the listener hard-codes InetAddress.getLoopbackAddress().

Example fix

// before
-Djunit.platform.reporting.open.xml.socket=9999  // (no server listening)

// after
// remove the property, or start the server first on 127.0.0.1:9999

// If the socket transport is requested, probe loopback reachability before the run.
String portProp = System.getProperty("junit.platform.reporting.open.xml.socket");
if (portProp != null) {
    int port = Integer.parseInt(portProp);
    try (Socket probe = new Socket()) {
        probe.connect(new InetSocketAddress(InetAddress.getLoopbackAddress(), port), 1000);
    } catch (IOException e) {
        System.clearProperty("junit.platform.reporting.open.xml.socket");
        // falls back to file-based open-test-report.xml
    }
}

try {
    launcher.execute(request);
} catch (JUnitException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to connect to socket on port")) {
        // Consumer not running; clear the socket property and retry with file output.
    } else {
        throw e;
    }
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Failed to create output dir
• Failed to start process
• Failed to create output directory
• The following TestInstanceFactory extensions were registered
• Timeout duration is not in the expected format (<number> [ns

AI-assisted analysis of junit-team/junit5@f070c699a0 (2026-08-11). Data as JSON: /api/errors/0fd51383791abac2. Report an issue: GitHub.