alibaba/spring-ai-alibaba · warning

Failed to load agent spec from

Error message

Failed to load agent spec from {}: {}

What it means

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.

Solutions

1. Open the path from the log and fix the front matter: valid YAML between opening and closing '---' lines.
2. Validate the YAML with a linter; replace tabs with spaces and quote values containing colons.
3. Check file read permissions for the process user.
4. Compare against a known-good example spec and align fields/naming with the current AgentSpec schema.

Example fix

// before (agents/broken.md)
---
name: my agent
description: uses: colons unquoted
---
// after
---
name: my-agent
description: "uses: colons quoted"
---

for (Path p : specFiles) { try { AgentSpecLoader.loadFromFile(p); } catch (Exception e) { throw new IllegalStateException("Invalid agent spec: " + p, e); } }

try { loadAllSpecs(); } catch (Exception e) { /* collect and report every failing spec path at startup */ }

When it happens

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

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

Related errors

• Agent spec must start with YAML front matter (---)
• 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/7fb61aae111a00dd. 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:100

		}
		if (!Files.isDirectory(rootPath)) {
			throw new IOException("Path is not a directory: " + rootPath);
		}

		List<AgentSpec> specs = new ArrayList<>();
		try (Stream<Path> paths = Files.walk(rootPath)) {
			paths.filter(Files::isRegularFile)
					.filter(p -> p.getFileName().toString().endsWith(".md"))
					.forEach(path -> {
						try {
							AgentSpec spec = loadFromFile(path);
							if (spec != null) {
								specs.add(spec);
								logger.debug("Loaded agent spec: {} from {}", spec.name(), path);
							}
						}
						catch (Exception e) {
							logger.warn("Failed to load agent spec from {}: {}", path, e.getMessage());
						}
					});
		}
		return specs;
	}

	/**
	 * Load a single agent spec from a file.
	 */
	public static AgentSpec loadFromFile(Path filePath) throws IOException {
		String content = Files.readString(filePath, StandardCharsets.UTF_8);
		return parse(content);
	}

	/**
	 * Load agent spec from a Spring Resource.
	 */
	public static AgentSpec loadFromResource(Resource resource) throws IOException {

View on GitHub (pinned to f82da0b50f)