alibaba/spring-ai-alibaba · error · RuntimeException

Failed to load agent spec from

Error message

Failed to load agent spec from 

What it means

loadFromFiles wraps IOExceptions from AgentSpecLoader.loadFromResource in a RuntimeException ('Failed to load agent spec from <resource>'). The classpath or filesystem resource holding a single agent .md spec could not be read or parsed.

Solutions

1. Check the cause for the real parse/read error.
2. Verify the resource path exists (resource.exists()) and is on the classpath (include it in jar resources).
3. Fix the .md spec content so AgentSpecLoader can parse it.

Example fix

// before
Resource res = new ClassPathResource("agent/my-agent.md"); // misspelled path
// after
Resource res = new ClassPathResource("agents/my-agent.md");

if (!resource.exists()) throw new IllegalStateException("Agent spec resource missing: " + resource);

try { spec = AgentSpecLoader.loadFromResource(res); } catch (RuntimeException e) { log.error("Bad agent resource {}: {}", res, e.getCause().getMessage(), e); }

When it happens

Trigger: Passing a Spring Resource (classpath:/agents/foo.md, file: URL, etc.) to TaskToolsBuilder.fromFiles where getInputStream() fails or the spec parsing throws IOException.

Common situations: Typo in classpath resource path; resource not packaged into the jar; @Value-injected resource pointing to a missing file; malformed agent spec markdown.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Failed to load agent specs from
• Path is not a directory:
• Agent spec directory does not exist
• Agent spec must start with YAML front matter (---)
• 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/42e6e2a4551d59b5. Report an issue: GitHub.

Appendix: source

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

			try {
				List<AgentSpec> specs = AgentSpecLoader.loadFromDirectory(dir);
				for (AgentSpec spec : specs) {
					result.put(spec.name(), factory.create(spec));
				}
			}
			catch (IOException e) {
				throw new RuntimeException("Failed to load agent specs from " + dir, e);
			}
		}
		for (Resource resource : agentResources) {
			try {
				AgentSpec spec = AgentSpecLoader.loadFromResource(resource);
				if (spec != null) {
					result.put(spec.name(), factory.create(spec));
				}
			}
			catch (IOException e) {
				throw new RuntimeException("Failed to load agent spec from " + resource, e);
			}
		}
		return result.isEmpty() ? null : result;
	}
}

View on GitHub (pinned to f82da0b50f)