{"record":{"id":"7fb61aae111a00dd","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-load-agent-spec-from-7fb61a","errorCode":null,"errorMessage":"Failed to load agent spec from {}: {}","messagePattern":"Failed to load agent spec from (.+?): (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/task/AgentSpecLoader.java","lineNumber":100,"sourceCode":"\t\t}\n\t\tif (!Files.isDirectory(rootPath)) {\n\t\t\tthrow new IOException(\"Path is not a directory: \" + rootPath);\n\t\t}\n\n\t\tList<AgentSpec> specs = new ArrayList<>();\n\t\ttry (Stream<Path> paths = Files.walk(rootPath)) {\n\t\t\tpaths.filter(Files::isRegularFile)\n\t\t\t\t\t.filter(p -> p.getFileName().toString().endsWith(\".md\"))\n\t\t\t\t\t.forEach(path -> {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tAgentSpec spec = loadFromFile(path);\n\t\t\t\t\t\t\tif (spec != null) {\n\t\t\t\t\t\t\t\tspecs.add(spec);\n\t\t\t\t\t\t\t\tlogger.debug(\"Loaded agent spec: {} from {}\", spec.name(), path);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\tcatch (Exception e) {\n\t\t\t\t\t\t\tlogger.warn(\"Failed to load agent spec from {}: {}\", path, e.getMessage());\n\t\t\t\t\t\t}\n\t\t\t\t\t});\n\t\t}\n\t\treturn specs;\n\t}\n\n\t/**\n\t * Load a single agent spec from a file.\n\t */\n\tpublic static AgentSpec loadFromFile(Path filePath) throws IOException {\n\t\tString content = Files.readString(filePath, StandardCharsets.UTF_8);\n\t\treturn parse(content);\n\t}\n\n\t/**\n\t * Load agent spec from a Spring Resource.\n\t */\n\tpublic static AgentSpec loadFromResource(Resource resource) throws IOException {","sourceCodeStart":82,"sourceCodeEnd":118,"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/AgentSpecLoader.java#L82-L118","documentation":"While recursively scanning the agent spec directory, an individual .md file failed to load or parse; the loader catches the exception, logs this warning with the path and message, skips that file, and continues loading the remaining specs.","triggerScenarios":"A .md spec file with invalid YAML front matter, an unreadable file (permissions), or any exception thrown inside spec parsing during the walk of the specs directory.","commonSituations":"Hand-edited agent markdown with broken YAML (bad indentation, tabs, unquoted colon values), a spec referencing an unsupported field, mixed old/new spec format after a version upgrade.","solutions":["Open the path from the log and fix the front matter: valid YAML between opening and closing '---' lines.","Validate the YAML with a linter; replace tabs with spaces and quote values containing colons.","Check file read permissions for the process user.","Compare against a known-good example spec and align fields/naming with the current AgentSpec schema."],"exampleFix":"// before (agents/broken.md)\n---\nname: my agent\ndescription: uses: colons unquoted\n---\n// after\n---\nname: my-agent\ndescription: \"uses: colons quoted\"\n---","handlingStrategy":"validation","validationCode":"for (Path p : specFiles) { try { AgentSpecLoader.loadFromFile(p); } catch (Exception e) { throw new IllegalStateException(\"Invalid agent spec: \" + p, e); } }","typeGuard":null,"tryCatchPattern":"try { loadAllSpecs(); } catch (Exception e) { /* collect and report every failing spec path at startup */ }","preventionTips":["Lint all spec .md files' YAML front matter in CI before deployment.","Quote YAML values containing colons; never use tabs.","Keep specs aligned with the current AgentSpec schema after upgrades."],"tags":["yaml","parse","agent-spec","markdown"],"backgroundTag":"yaml-parse-error","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"}