junit-team/junit5 · error · JUnitException

Failed to connect to socket on port

Error message

Failed to connect to socket on port 

What it means

Thrown by OpenTestReportGeneratingListener.createDocumentWriter() when the SOCKET_PROPERTY_NAME (junit.platform.reporting.open.xml.socket) is set to a port but opening a Socket to InetAddress.getLoopbackAddress() on that port fails. Wrapped as a JUnitException naming the port. Only reached when XML reporting is enabled and the socket property is present.

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 956246301e)

Solutions

1. Ensure the report server is listening on 127.0.0.1 at the configured port before tests start.
2. Double-check the port value in junit.platform.reporting.open.xml.socket.
3. If you do not want socket-based reporting, remove the property to fall back to file output.
4. Bind the server to loopback since the listener uses InetAddress.getLoopbackAddress().

Example fix

# before
junit.platform.reporting.open.xml.socket = 12345
# nothing listening on 12345 -> JUnitException

# after: start the server first, or drop socket mode
# (remove the property to write open-test-report.xml to disk)

int port = Integer.parseInt(System.getProperty("junit.platform.reporting.open.xml.socket"));
try (Socket s = new Socket(InetAddress.getLoopbackAddress(), port)) {
    // reachable
} catch (IOException e) {
    throw new IllegalStateException("report socket server not listening on " + port);
}

static boolean socketListening(int port) {
    try (Socket s = new Socket(InetAddress.getLoopbackAddress(), port)) { return true; }
    catch (IOException e) { return false; }
}

try {
    new Socket(InetAddress.getLoopbackAddress(), port);
} catch (IOException e) {
    // start the server first, or unset the socket property to use file output
}

When it happens

Trigger: Setting junit.platform.reporting.open.xml.socket=<port> with XML reporting enabled, when no server is listening on loopback at that port, the port is invalid, or the connection is refused.

Common situations: Starting the launcher before the report-consuming socket server is up. Wrong port number. Server bound to a non-loopback address (the listener only connects to loopback). Firewall blocking loopback. Test orchestration race between listener and server.

Related errors

• Cannot override the standard style 'NONE'
• Could not read color palette properties
• Could not open color palette properties file
• Failed to transform configuration parameter with key '%s' an
• Failed to create ForkJoinPool

AI-assisted analysis of junit-team/junit5@956246301e (2026-08-04). Data as JSON: /data/errors/0e22fc234b61e5af.json. Report an issue: GitHub.