spring-projects/spring-ai · error · RuntimeException

Failed to read stdio connection resource

Error message

Failed to read stdio connection resource

What it means

McpStdioClientProperties.toServerParameters loads stdio connection definitions from a classpath/file resource and converts them into MCP ServerParameters. If reading or parsing that resource fails for any reason, the method wraps the cause in a RuntimeException with this message, preserving the original exception.

Source

Thrown at auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/properties/McpStdioClientProperties.java:98

			return Collections.emptyMap();
		}
		try {
			Map<String, Map<String, Parameters>> stdioConnection = JsonMapper.shared()
				.readValue(this.serversConfiguration.getInputStream(), new TypeReference<>() {
				});

			Map<String, Parameters> mcpServerJsonConfig = stdioConnection.entrySet().iterator().next().getValue();

			return mcpServerJsonConfig.entrySet().stream().collect(Collectors.toMap(kv -> kv.getKey(), kv -> {
				Parameters parameters = kv.getValue();
				return ServerParameters.builder(parameters.command())
					.args(parameters.argsOrEmpty())
					.env(parameters.env())
					.build();
			}));
		}
		catch (Exception e) {
			throw new RuntimeException("Failed to read stdio connection resource", e);
		}
	}

	public Map<String, ServerParameters> toServerParameters() {
		Map<String, ServerParameters> serverParameters = new HashMap<>();
		serverParameters.putAll(resourceToServerParameters());

		for (Map.Entry<String, Parameters> entry : this.connections.entrySet()) {
			serverParameters.put(entry.getKey(), entry.getValue().toServerParameters());
		}
		return serverParameters;
	}

	/**
	 * Record representing the parameters for an MCP server connection.
	 * <p>
	 * Includes the command to execute, command arguments, and environment variables.
	 */

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Read the 'Caused by' of the thrown exception — it names the exact missing file or parse error.
2. Verify the resource path configured for the stdio connections spec exists on the classpath/filesystem at runtime.
3. Validate the JSON structure of the connections spec (command, args, env per server).
4. Ensure the file is packaged into the jar/container (check Dockerfile COPY and build resource includes).

Example fix

# before (file not packaged)
spring.ai.mcp.client.stdio.connections-spec=classpath:mcp-stdio.json

# after: add to src/main/resources or use a file: URL that exists
spring.ai.mcp.client.stdio.connections-spec=file:/etc/mcp/stdio.json

Resource r = new DefaultResourceLoader().getResource(specLocation);
if (!r.exists()) {
    throw new IllegalStateException("MCP stdio connections spec not found: " + specLocation);
}
// plus parse validation before auto-configuration runs

try {
    Map<String, ServerParameters> params = stdioProperties.toServerParameters();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Failed to read stdio connection resource")) {
        // inspect e.getCause() for the exact file/JSON problem
    }
    throw e;
}

When it happens

Trigger: Calling toServerParameters (invoked during MCP client auto-configuration) when the configured stdio connections resource (spring.ai.mcp.client.stdio.connections-spec / JSON spec file) is missing, unreadable, or malformed.

Common situations: Wrong path in spring.ai.mcp.client.stdio.file/connections resource, missing file in a container image, JSON syntax errors, file permission issues, or resources stripped during packaging.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• SSE connection '<connectionName>' requires a 'url' property.
• Failed to create SSE transport for connection '<connectionNa
• Multiple tools with the same name (%s)
• Multiple tools with the same name (%s)
• At least one client Id must be specified

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/76f1ea8b658bee6c. Report an issue: GitHub.