alibaba/spring-ai-alibaba · error · IllegalArgumentException

Routing flow requires a ChatModel for decision making

Error message

Routing flow requires a ChatModel for decision making

What it means

validateRoutingConfig in RoutingGraphBuildingStrategy requires config.getChatModel() to be non-null: the routing agent uses an LLM to decide which sub-agent to invoke, so a missing ChatModel makes the flow unbuildable.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/RoutingGraphBuildingStrategy.java:155

	@Override
	public void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {
		super.validateConfig(config);
		validateRoutingConfig(config);
	}

	/**
	 * Validates routing-specific configuration requirements.
	 * @param config the configuration to validate
	 * @throws IllegalArgumentException if validation fails
	 */
	private void validateRoutingConfig(FlowGraphBuilder.FlowGraphConfig config) {
		if (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {
			throw new IllegalArgumentException("Routing flow requires at least one sub-agent");
		}

		if (config.getChatModel() == null) {
			throw new IllegalArgumentException("Routing flow requires a ChatModel for decision making");
		}

		// Ensure root agent is a FlowAgent for input key access
		if (!(config.getRootAgent() instanceof FlowAgent)) {
			throw new IllegalArgumentException("Routing flow requires root agent to be a FlowAgent");
		}
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a ChatModel to the routing agent builder (.chatModel(model))
2. Verify the model bean is properly injected and not null
3. Construct a DashScopeChatModel/OpenAiChatModel instance if none is configured

Example fix

// before
RoutingAgent.builder().subAgents(a, b).build();
// after
RoutingAgent.builder().chatModel(new DashScopeChatModel(apiKey)).subAgents(a, b).build();

if (chatModel == null) {
    throw new IllegalArgumentException("Routing requires a ChatModel; configure it via .chatModel(...)");
}

When it happens

Trigger: Building a routing flow without calling .chatModel(...) / without a model configured on the root agent, so getChatModel() returns null at validation time.

Common situations: Forgot to wire the DashScope/OpenAI model into the routing builder; model bean not injected (null autowire); copying a non-routing agent template that has no model.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Routing sub-agents must be BaseAgent for merge support
• Routing flow requires at least one sub-agent
• Routing flow requires root agent to be a FlowAgent
• No default output or error next node provided
• Parallel flow requires root agent to be a FlowAgent

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/7fdf5dc4456a7353. Report an issue: GitHub.