{"record":{"id":"9d9df5f6ad584d9f","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-load-agent-specs-from","errorCode":null,"errorMessage":"Failed to load agent specs from ","messagePattern":"Failed to load agent specs 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":249,"sourceCode":"\t\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\t\"chatModel or chatClient must be provided for file-based agent loading\");\n\t\t\t}\n\t\t\tif (!this.defaultTools.isEmpty()) {\n\t\t\t\tfb.defaultTools(this.defaultTools);\n\t\t\t}\n\t\t\tfactory = fb.build();\n\t\t}\n\n\t\tMap<String, ReactAgent> result = new HashMap<>();\n\t\tfor (String dir : agentDirectories) {\n\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":231,"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#L231-L266","documentation":"loadFromFiles wraps IOExceptions from AgentSpecLoader.loadFromDirectory in a RuntimeException ('Failed to load agent specs from <dir>') with the original as cause. The directory existed and was a directory, but reading/walking it or parsing failed.","triggerScenarios":"Files.walk(rootPath) throwing mid-iteration (I/O error, permissions) while AgentSpecLoader.loadFromDirectory processes the directory passed to TaskToolsBuilder.fromFiles.","commonSituations":"Unreadable directories due to file permissions; broken symlinks inside the tree; I/O errors on network mounts; spec files deleted between existence check and walk.","solutions":["Inspect the cause (e.getCause()) to find the underlying IOException location.","Fix filesystem permissions on the agent spec directory.","Verify the directory and all .md files are readable by the process user; avoid network mounts for spec dirs if flaky."],"exampleFix":"// before\ncatch (IOException e) { /* surface as 'Failed to load agent specs from <dir>' */ }\n// after\n// log or handle the wrapped cause:\ntry { ... } catch (RuntimeException e) { log.error(\"spec load failed\", e.getCause()); }","handlingStrategy":"try-catch","validationCode":"if (dir != null && Files.isDirectory(dir) && Files.isReadable(dir)) { /* safe to load */ }","typeGuard":null,"tryCatchPattern":"try { specs = AgentSpecLoader.loadFromDirectory(dir); } catch (RuntimeException e) { log.error(\"Failed loading specs from {}: cause={}\", dir, e.getCause(), e); }","preventionTips":["Verify read permissions on the spec directory for the running user.","Keep spec directories on local, stable storage.","Log the wrapped cause explicitly; the outer message only names the directory."],"tags":["io","agent-spec","file-loading"],"backgroundTag":"file-read-failed","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"}