alibaba/spring-ai-alibaba · error · IllegalArgumentException

Routing flow requires at least one sub-agent

Error message

Routing flow requires at least one sub-agent

What it means

validateRoutingConfig in RoutingGraphBuildingStrategy throws IllegalArgumentException when a routing (Router) flow is built with no sub-agents — there would be nothing to route to, so config is rejected before graph construction.

Source

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

			strategies.put(RoutingMergeNode.DEFAULT_MERGED_OUTPUT_KEY, new ReplaceStrategy());
			return strategies;
		};
	}

	@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. Register at least one sub-agent via the builder's subAgents(...) method
2. Check that branch-adding code actually executed (no early return before adding)
3. Assert subAgents is non-empty before calling build()

Example fix

// before
RoutingAgent.builder().chatModel(model).build();
// after
RoutingAgent.builder().chatModel(model).subAgents(agentA, agentB).build();

if (subAgents == null || subAgents.isEmpty()) {
    throw new IllegalArgumentException("Routing flow requires at least one sub-agent");
}

static boolean hasBranches(List<? extends Agent> l) { return l != null && !l.isEmpty(); }

When it happens

Trigger: Building a RoutingAgent/flow graph with subAgents left unset, set to an empty list, or cleared before buildCoreGraph/validateConfig runs.

Common situations: Forgetting to call .subAgents(...) on the builder; programmatically constructing config where the list population was skipped; conditional code that adds no branches.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Routing flow requires root agent to be a FlowAgent
• Parallel flow requires root agent to be a FlowAgent
• maxConcurrency must be at least 1, but got:
• Routing sub-agents must be BaseAgent for merge support
• Routing flow requires a ChatModel for decision making

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