alibaba/spring-ai-alibaba · error · IllegalArgumentException

ChatModel must be provided for LLM routing agent

Error message

ChatModel must be provided for LLM routing agent

What it means

LlmRoutingAgent delegates routing decisions to an LLM, so its builder's validate() (invoked from doBuild()) requires a ChatModel. Building without one means the agent could not choose among its sub-agents, so it fails fast with IllegalArgumentException.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/LlmRoutingAgent.java:108

			this.systemPrompt = systemPrompt;
			return this;
		}

		public LlmRoutingAgentBuilder instruction(String instruction) {
			this.instruction = instruction;
			return this;
		}

		@Override
		protected LlmRoutingAgentBuilder self() {
			return this;
		}

		@Override
		protected void validate() {
			super.validate();
			if (chatModel == null) {
				throw new IllegalArgumentException("ChatModel must be provided for LLM routing agent");
			}
		}

		@Override
		public LlmRoutingAgent doBuild() {
			validate();
			return new LlmRoutingAgent(this);
		}

	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add chatModel(model) to the builder with a configured ChatModel bean (e.g., DashScopeChatModel or OpenAiChatModel).
2. Verify the model bean actually initialized — a null usually indicates a missing starter dependency or API key so the auto-configured bean was absent.
3. If routing should be rule-based instead, use a different (non-LLM) routing agent type that does not require a ChatModel.

Example fix

// before
LlmRoutingAgent agent = LlmRoutingAgent.builder()
    .name("router")
    .subAgents(specA, specB)
    .build(); // throws: ChatModel must be provided
// after
LlmRoutingAgent agent = LlmRoutingAgent.builder()
    .name("router")
    .chatModel(chatModel)
    .subAgents(specA, specB)
    .build();

Objects.requireNonNull(chatModel, "LlmRoutingAgent requires a configured ChatModel bean");
LlmRoutingAgent agent = LlmRoutingAgent.builder().chatModel(chatModel)...build();

static boolean readyForBuild(LlmRoutingAgent.Builder b) { return b != null; } // ensure model injected via constructor/bean before building

try {
    agent = llmRoutingBuilder.build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("ChatModel")) {
        log.error("ChatModel bean missing; check DashScope/OpenAI starter and API key");
    }
}

When it happens

Trigger: Calling LlmRoutingAgent.builder()...build() (which calls doBuild -> validate) without a chatModel(...) call, or passing null to chatModel().

Common situations: Assembling the agent in a conditional code path where the model bean is null due to a missing DashScope/OpenAI starter or API key; refactoring that removed the model builder call; copying a graph-structured agent example that does not need a model into an LLM-routing agent.

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

• model must be specified
• SubAgent name is required
• SubAgent description is required
• SubAgent system prompt is required
• LoopAgent must have a loopStrategy.

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