alibaba/spring-ai-alibaba · warning

Agent spec directory does not exist

Error message

Agent spec directory does not exist: {}

What it means

AgentSpecLoader.loadFromDirectory was given a null or non-existent root path; it logs this warning and returns an empty list instead of throwing, so callers get zero agent specs loaded. This is a configuration problem: the directory you pointed the loader at is not present on disk.

Solutions

1. Verify the path exists before loading: Files.exists(rootPath) and Files.isDirectory(rootPath).
2. Fix the configured directory path (check for typos and relative vs absolute resolution against the working directory).
3. Ensure the directory is packaged into the deployment artifact (e.g. add it to the container image or resources).
4. Create the directory with at least one .md spec file if it is meant to be populated.

Example fix

// before
Path dir = Path.of("agents");
var specs = AgentSpecLoader.loadFromDirectory(dir);
// after
Path dir = Path.of("/app/config/agents");
if (!Files.isDirectory(dir)) throw new IllegalStateException("Agent spec dir missing: " + dir);
var specs = AgentSpecLoader.loadFromDirectory(dir);

if (rootPath == null || !Files.isDirectory(rootPath)) throw new IllegalStateException("Agent spec directory missing: " + rootPath);

var specs = AgentSpecLoader.loadFromDirectory(dir); if (specs.isEmpty()) log.warn("No agent specs loaded from {}", dir);

When it happens

Trigger: Calling loadFromDirectory(Path) with a path that was never created, was deleted, or is null; configuring an agent-spec directory property with a typo or a path valid on the dev machine but missing in the deployment container.

Common situations: Docker image not copying the agents directory, working-directory differences making a relative path resolve elsewhere, renamed/moved spec folder after an upgrade.

Related errors

• 启动 WatchService 失败，将不进行热更新
• Agent spec must start with YAML front matter (---)
• APP_COMPONENT_QUERYCONFIG_ERROR
• Cannot convert resource to file system path:
• Cannot convert resource to file system path

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/93ea99591524a1b3. 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:80

	/**
	 * Load agent specs from a directory (recursively scans for .md files).
	 * @param directoryPath path to directory containing agent spec files
	 * @return list of parsed specs
	 */
	public static List<AgentSpec> loadFromDirectory(String directoryPath) throws IOException {
		if (!StringUtils.hasText(directoryPath)) {
			return List.of();
		}
		return loadFromDirectory(Paths.get(directoryPath));
	}

	/**
	 * Load agent specs from a directory (recursively scans for .md files).
	 */
	public static List<AgentSpec> loadFromDirectory(Path rootPath) throws IOException {
		if (rootPath == null || !Files.exists(rootPath)) {
			logger.warn("Agent spec directory does not exist: {}", rootPath);
			return List.of();
		}
		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);
							}
						}

View on GitHub (pinned to f82da0b50f)