alibaba/spring-ai-alibaba · error · IllegalArgumentException

Root agent must be provided

Error message

Root agent must be provided

What it means

A flow graph must have a root agent to serve as entry point; validateConfig throws IllegalArgumentException when config.getRootAgent() is null. The root agent also determines generated key strategies, so building cannot continue.

Source

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

	 * @return the strategy type identifier
	 */
	String getStrategyType();

	/**
	 * Validates that the configuration contains all required parameters for this
	 * strategy.
	 * @param config the configuration to validate
	 * @throws IllegalArgumentException if validation fails
	 */
	default void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {
		if (config == null) {
			throw new IllegalArgumentException("Configuration cannot be null");
		}
		if (config.getName() == null || config.getName().trim().isEmpty()) {
			throw new IllegalArgumentException("Graph name must be provided");
		}
		if (config.getRootAgent() == null) {
			throw new IllegalArgumentException("Root agent must be provided");
		}
		if (config.getKeyStrategyFactory() == null) {
			// Generate a new KeyStrategyFactory based on agent keys
			KeyStrategyFactory generatedFactory = generateKeyStrategyFactory(config);
			config.keyStrategyFactory(generatedFactory);
		}
	}

	/**
	 * Generates a KeyStrategyFactory based on the root agent and sub-agents.
	 * @param config the configuration containing agents
	 * @return the generated KeyStrategyFactory
	 */
	default KeyStrategyFactory generateKeyStrategyFactory(FlowGraphBuilder.FlowGraphConfig config) {
		return () -> {
			Map<String, KeyStrategy> keyStrategyMap = new HashMap<>();
			KeyStrategy defaultStrategy = new ReplaceStrategy();

View on GitHub (pinned to f82da0b50f)

Solutions

1. Call .rootAgent(agent) with a fully constructed agent before build()
2. Verify agent construction did not return null (check factory/bean creation logs)
3. Fix Spring wiring order so the agent bean exists when the graph is built

Example fix

// before
FlowGraphBuilder.builder().name("flow").build(); // no root
// after
FlowGraphBuilder.builder().name("flow").rootAgent(myAgent).build();

Objects.requireNonNull(agent, "Root agent must be constructed before building the flow graph");

static boolean hasRoot(FlowGraphBuilder.FlowGraphConfig c) { return c.getRootAgent() != null; }

try { return builder.build(); } catch (IllegalArgumentException e) { throw new FlowBuildException("Graph build failed: " + e.getMessage(), e); }

When it happens

Trigger: Builder used without rootAgent(...), or root agent variable still null because agent construction failed earlier / was conditional.

Common situations: Instantiating the builder before the agent is created; a factory method returning null on failed agent initialization; wiring order issues in Spring configuration.

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

• Conditional flow requires at least one conditional agent map
• Graph name must be provided
• WORKFLOW_CONFIG_ILLEGAL
• 模型缺少 id
• 模型缺少 name

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