{"record":{"id":"76f1ea8b658bee6c","repo":"spring-projects/spring-ai","slug":"failed-to-read-stdio-connection-resource","errorCode":null,"errorMessage":"Failed to read stdio connection resource","messagePattern":"Failed to read stdio connection resource","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/properties/McpStdioClientProperties.java","lineNumber":98,"sourceCode":"\t\t\treturn Collections.emptyMap();\n\t\t}\n\t\ttry {\n\t\t\tMap<String, Map<String, Parameters>> stdioConnection = JsonMapper.shared()\n\t\t\t\t.readValue(this.serversConfiguration.getInputStream(), new TypeReference<>() {\n\t\t\t\t});\n\n\t\t\tMap<String, Parameters> mcpServerJsonConfig = stdioConnection.entrySet().iterator().next().getValue();\n\n\t\t\treturn mcpServerJsonConfig.entrySet().stream().collect(Collectors.toMap(kv -> kv.getKey(), kv -> {\n\t\t\t\tParameters parameters = kv.getValue();\n\t\t\t\treturn ServerParameters.builder(parameters.command())\n\t\t\t\t\t.args(parameters.argsOrEmpty())\n\t\t\t\t\t.env(parameters.env())\n\t\t\t\t\t.build();\n\t\t\t}));\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new RuntimeException(\"Failed to read stdio connection resource\", e);\n\t\t}\n\t}\n\n\tpublic Map<String, ServerParameters> toServerParameters() {\n\t\tMap<String, ServerParameters> serverParameters = new HashMap<>();\n\t\tserverParameters.putAll(resourceToServerParameters());\n\n\t\tfor (Map.Entry<String, Parameters> entry : this.connections.entrySet()) {\n\t\t\tserverParameters.put(entry.getKey(), entry.getValue().toServerParameters());\n\t\t}\n\t\treturn serverParameters;\n\t}\n\n\t/**\n\t * Record representing the parameters for an MCP server connection.\n\t * <p>\n\t * Includes the command to execute, command arguments, and environment variables.\n\t */","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/properties/McpStdioClientProperties.java#L80-L116","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the 'Caused by' of the thrown exception — it names the exact missing file or parse error.","Verify the resource path configured for the stdio connections spec exists on the classpath/filesystem at runtime.","Validate the JSON structure of the connections spec (command, args, env per server).","Ensure the file is packaged into the jar/container (check Dockerfile COPY and build resource includes)."],"exampleFix":"# before (file not packaged)\nspring.ai.mcp.client.stdio.connections-spec=classpath:mcp-stdio.json\n\n# after: add to src/main/resources or use a file: URL that exists\nspring.ai.mcp.client.stdio.connections-spec=file:/etc/mcp/stdio.json","handlingStrategy":"validation","validationCode":"Resource r = new DefaultResourceLoader().getResource(specLocation);\nif (!r.exists()) {\n    throw new IllegalStateException(\"MCP stdio connections spec not found: \" + specLocation);\n}\n// plus parse validation before auto-configuration runs","typeGuard":null,"tryCatchPattern":"try {\n    Map<String, ServerParameters> params = stdioProperties.toServerParameters();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Failed to read stdio connection resource\")) {\n        // inspect e.getCause() for the exact file/JSON problem\n    }\n    throw e;\n}","preventionTips":["Always check e.getCause() — the wrapper hides the real reason","Verify spec file presence in Docker images and jars","Validate spec JSON with a linter before deploy","Prefer file: URLs over classpath for externally managed config"],"tags":["mcp","stdio","resource-loading","configuration"],"backgroundTag":"file-read-failed","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}