alibaba/spring-ai-alibaba · error · RuntimeException

Failed to load agent specs from

Error message

Failed to load agent specs from 

What it means

loadFromFiles wraps IOExceptions from AgentSpecLoader.loadFromDirectory in a RuntimeException ('Failed to load agent specs from <dir>') with the original as cause. The directory existed and was a directory, but reading/walking it or parsing failed.

Solutions

1. Inspect the cause (e.getCause()) to find the underlying IOException location.
2. Fix filesystem permissions on the agent spec directory.
3. Verify the directory and all .md files are readable by the process user; avoid network mounts for spec dirs if flaky.

Example fix

// before
catch (IOException e) { /* surface as 'Failed to load agent specs from <dir>' */ }
// after
// log or handle the wrapped cause:
try { ... } catch (RuntimeException e) { log.error("spec load failed", e.getCause()); }

if (dir != null && Files.isDirectory(dir) && Files.isReadable(dir)) { /* safe to load */ }

try { specs = AgentSpecLoader.loadFromDirectory(dir); } catch (RuntimeException e) { log.error("Failed loading specs from {}: cause={}", dir, e.getCause(), e); }

When it happens

Trigger: Files.walk(rootPath) throwing mid-iteration (I/O error, permissions) while AgentSpecLoader.loadFromDirectory processes the directory passed to TaskToolsBuilder.fromFiles.

Common situations: Unreadable directories due to file permissions; broken symlinks inside the tree; I/O errors on network mounts; spec files deleted between existence check and walk.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Path is not a directory:
• Failed to load agent spec from
• 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/9d9df5f6ad584d9f. 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:249

				throw new IllegalStateException(
						"chatModel or chatClient must be provided for file-based agent loading");
			}
			if (!this.defaultTools.isEmpty()) {
				fb.defaultTools(this.defaultTools);
			}
			factory = fb.build();
		}

		Map<String, ReactAgent> result = new HashMap<>();
		for (String dir : agentDirectories) {
			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)