{"record":{"id":"42e6e2a4551d59b5","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-load-agent-spec-from","errorCode":null,"errorMessage":"Failed to load agent spec from ","messagePattern":"Failed to load agent spec from ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/task/TaskToolsBuilder.java","lineNumber":260,"sourceCode":"\t\t\ttry {\n\t\t\t\tList<AgentSpec> specs = AgentSpecLoader.loadFromDirectory(dir);\n\t\t\t\tfor (AgentSpec spec : specs) {\n\t\t\t\t\tresult.put(spec.name(), factory.create(spec));\n\t\t\t\t}\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tthrow new RuntimeException(\"Failed to load agent specs from \" + dir, e);\n\t\t\t}\n\t\t}\n\t\tfor (Resource resource : agentResources) {\n\t\t\ttry {\n\t\t\t\tAgentSpec spec = AgentSpecLoader.loadFromResource(resource);\n\t\t\t\tif (spec != null) {\n\t\t\t\t\tresult.put(spec.name(), factory.create(spec));\n\t\t\t\t}\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tthrow new RuntimeException(\"Failed to load agent spec from \" + resource, e);\n\t\t\t}\n\t\t}\n\t\treturn result.isEmpty() ? null : result;\n\t}\n}\n","sourceCodeStart":242,"sourceCodeEnd":266,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/task/TaskToolsBuilder.java#L242-L266","documentation":"loadFromFiles wraps IOExceptions from AgentSpecLoader.loadFromResource in a RuntimeException ('Failed to load agent spec from <resource>'). The classpath or filesystem resource holding a single agent .md spec could not be read or parsed.","triggerScenarios":"Passing a Spring Resource (classpath:/agents/foo.md, file: URL, etc.) to TaskToolsBuilder.fromFiles where getInputStream() fails or the spec parsing throws IOException.","commonSituations":"Typo in classpath resource path; resource not packaged into the jar; @Value-injected resource pointing to a missing file; malformed agent spec markdown.","solutions":["Check the cause for the real parse/read error.","Verify the resource path exists (resource.exists()) and is on the classpath (include it in jar resources).","Fix the .md spec content so AgentSpecLoader can parse it."],"exampleFix":"// before\nResource res = new ClassPathResource(\"agent/my-agent.md\"); // misspelled path\n// after\nResource res = new ClassPathResource(\"agents/my-agent.md\");","handlingStrategy":"try-catch","validationCode":"if (!resource.exists()) throw new IllegalStateException(\"Agent spec resource missing: \" + resource);","typeGuard":null,"tryCatchPattern":"try { spec = AgentSpecLoader.loadFromResource(res); } catch (RuntimeException e) { log.error(\"Bad agent resource {}: {}\", res, e.getCause().getMessage(), e); }","preventionTips":["Verify resource.exists() and resource.getFilename() before loading.","Ensure .md spec files are under src/main/resources so they ship in the jar.","Validate spec markdown against AgentSpecLoader's expected front-matter format."],"tags":["io","agent-spec","classpath-resource"],"backgroundTag":"file-not-found","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}