alibaba/spring-ai-alibaba · warning

Agent spec must start with YAML front matter (---)

Error message

Agent spec must start with YAML front matter (---)

What it means

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.

Solutions

1. Add YAML front matter at the very top: '---' line, name/description fields, closing '---' line.
2. Strip any BOM or leading whitespace/newlines so the file literally begins with '---'.
3. Confirm the file extension is .md and it is inside the scanned directory.
4. Check the file parses as YAML between the delimiters to avoid the related 'not properly closed' warning.

Example fix

// before (spec.md)
# My Agent
Some description...
// after
---
name: my-agent
description: My agent description
---
# My Agent
Some description...

String normalized = markdown == null ? null : markdown.replace("\uFEFF", "").stripLeading();
if (normalized == null || !normalized.startsWith("---")) throw new IllegalStateException("Spec missing front matter");

AgentSpec spec = AgentSpecLoader.parse(md); if (spec == null) log.warn("Skipping file without front matter");

When it happens

Trigger: 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 '---'.

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Failed to load agent spec from
• Agent spec directory does not exist
• 模型缺少 apiKey
• BuildToolSchemaError
• chatModel or chatClient must be provided for file-based…

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/3a7c28fc53179922. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/task/AgentSpecLoader.java:131

	}

	/**
	 * Load agent spec from a Spring Resource.
	 */
	public static AgentSpec loadFromResource(Resource resource) throws IOException {
		String content = resource.getContentAsString(StandardCharsets.UTF_8);
		return parse(content);
	}

	/**
	 * Parse markdown content with YAML front matter into AgentSpec.
	 */
	public static AgentSpec parse(String markdown) {
		if (!StringUtils.hasText(markdown)) {
			return null;
		}
		if (!markdown.startsWith("---")) {
			logger.warn("Agent spec must start with YAML front matter (---)");
			return null;
		}

		int endIndex = markdown.indexOf("---", 3);
		if (endIndex == -1) {
			logger.warn("Agent spec front matter not properly closed with ---");
			return null;
		}

		String frontMatterStr = markdown.substring(3, endIndex).trim();
		String content = markdown.substring(endIndex + 3).trim();

		Map<String, Object> frontMatter;
		try {
			@SuppressWarnings("unchecked")
			Map<String, Object> parsed = YAML.load(frontMatterStr);
			frontMatter = parsed;
		}

View on GitHub (pinned to f82da0b50f)