alibaba/spring-ai-alibaba · error · IllegalStateException

chatModel or chatClient must be provided for file-based…

Error message

chatModel or chatClient must be provided for file-based agent loading

What it means

TaskToolsBuilder.loadFromFiles builds an AgentFactory for file-based agent specs, which requires an LLM. When neither chatModel nor chatClient was set on the builder, an IllegalStateException is thrown because file-loaded specs cannot be instantiated without a model.

Solutions

1. Call .chatModel(chatModel) on the TaskToolsBuilder before fromFiles/loadFromFiles.
2. Or call .chatClient(chatClient) if you have a composed ChatClient instead of a raw model.
3. Ensure a ChatModel/ChatClient bean is available (DashScope/OpenAI starter configured) and inject it into the builder.

Example fix

// before
TaskTools tools = TaskToolsBuilder.builder().build().loadFromFiles(List.of(Path.of("agents")));
// after
TaskTools tools = TaskToolsBuilder.builder()
    .chatModel(chatModel)
    .build()
    .loadFromFiles(List.of(Path.of("agents")));

if (builder.getChatModel() == null && builder.getChatClient() == null) throw new IllegalStateException("Set chatModel or chatClient before file-based loading");

boolean canLoadFromFiles(TaskToolsBuilder b) { return b.getChatModel() != null || b.getChatClient() != null; }

try { tools = builder.loadFromFiles(dirs); } catch (IllegalStateException e) { log.error("Missing model for agent loading", e); }

When it happens

Trigger: Calling TaskToolsBuilder.fromFiles(...) (or loading agents from directories/resources) without having called .chatModel(...) or .chatClient(...) on the builder.

Common situations: Configuring file-based agents in code that only wires tools; refactoring away a ChatClient bean and forgetting to set it on the builder; creating the builder via a factory method that doesn't inherit the model.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Agent spec directory does not exist
• Agent spec must start with YAML front matter (---)
• 模型缺少 apiKey
• AppNotFound
• At least one fallback model must be specified

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

		}
	}

	private Map<String, ReactAgent> loadFromFiles() {
		if (agentDirectories.isEmpty() && agentResources.isEmpty()) {
			return null;
		}

		AgentSpecReactAgentFactory factory = this.agentSpecFactory;
		if (factory == null) {
			AgentSpecReactAgentFactory.Builder fb = AgentSpecReactAgentFactory.builder();
			if (this.chatModel != null) {
				fb.chatModel(this.chatModel);
			}
			else if (this.chatClient != null) {
				fb.chatClient(this.chatClient);
			}
			else {
				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);

View on GitHub (pinned to f82da0b50f)