{"record":{"id":"3a7c28fc53179922","repo":"alibaba/spring-ai-alibaba","slug":"agent-spec-must-start-with-yaml-front-matter","errorCode":null,"errorMessage":"Agent spec must start with YAML front matter (---)","messagePattern":"Agent spec must start with YAML front matter \\(---\\)","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":131,"sourceCode":"\t}\n\n\t/**\n\t * Load agent spec from a Spring Resource.\n\t */\n\tpublic static AgentSpec loadFromResource(Resource resource) throws IOException {\n\t\tString content = resource.getContentAsString(StandardCharsets.UTF_8);\n\t\treturn parse(content);\n\t}\n\n\t/**\n\t * Parse markdown content with YAML front matter into AgentSpec.\n\t */\n\tpublic static AgentSpec parse(String markdown) {\n\t\tif (!StringUtils.hasText(markdown)) {\n\t\t\treturn null;\n\t\t}\n\t\tif (!markdown.startsWith(\"---\")) {\n\t\t\tlogger.warn(\"Agent spec must start with YAML front matter (---)\");\n\t\t\treturn null;\n\t\t}\n\n\t\tint endIndex = markdown.indexOf(\"---\", 3);\n\t\tif (endIndex == -1) {\n\t\t\tlogger.warn(\"Agent spec front matter not properly closed with ---\");\n\t\t\treturn null;\n\t\t}\n\n\t\tString frontMatterStr = markdown.substring(3, endIndex).trim();\n\t\tString content = markdown.substring(endIndex + 3).trim();\n\n\t\tMap<String, Object> frontMatter;\n\t\ttry {\n\t\t\t@SuppressWarnings(\"unchecked\")\n\t\t\tMap<String, Object> parsed = YAML.load(frontMatterStr);\n\t\t\tfrontMatter = parsed;\n\t\t}","sourceCodeStart":113,"sourceCodeEnd":149,"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#L113-L149","documentation":"AgentSpecLoader.parse requires agent spec markdown to begin with YAML front matter delimited by '---'. If the content is non-blank but does not start with '---', it logs this warning and returns null, meaning the file is silently skipped by callers like loadFromFile/loadFromResource.","triggerScenarios":"Loading an agent spec whose file is a plain markdown document without the '--- ... ---' header block, or one that starts with a BOM/whitespace/newline before the '---'.","commonSituations":"Authoring agent docs as ordinary README-style markdown, editors inserting a UTF-8 BOM or leading blank line, template files missing the front matter entirely.","solutions":["Add YAML front matter at the very top: '---' line, name/description fields, closing '---' line.","Strip any BOM or leading whitespace/newlines so the file literally begins with '---'.","Confirm the file extension is .md and it is inside the scanned directory.","Check the file parses as YAML between the delimiters to avoid the related 'not properly closed' warning."],"exampleFix":"// before (spec.md)\n# My Agent\nSome description...\n// after\n---\nname: my-agent\ndescription: My agent description\n---\n# My Agent\nSome description...","handlingStrategy":"validation","validationCode":"String normalized = markdown == null ? null : markdown.replace(\"\\uFEFF\", \"\").stripLeading();\nif (normalized == null || !normalized.startsWith(\"---\")) throw new IllegalStateException(\"Spec missing front matter\");","typeGuard":null,"tryCatchPattern":"AgentSpec spec = AgentSpecLoader.parse(md); if (spec == null) log.warn(\"Skipping file without front matter\");","preventionTips":["Start every spec file with an opening '---' on line 1.","Save files without BOM and without leading blank lines.","Use a template/spec skeleton when creating new agents."],"tags":["yaml","front-matter","agent-spec","markdown"],"backgroundTag":"schema-validation-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"}