alibaba/spring-ai-alibaba · error · IllegalArgumentException

AgentScope routing flow requires at least one sub-agent

Error message

AgentScope routing flow requires at least one sub-agent

What it means

AgentScopeRoutingGraphBuildingStrategy.validateAgentScopeRoutingConfig() (called from buildCoreGraph and validateConfig) requires a routing flow to declare at least one sub-agent. A routing agent routes among sub-agents, so an empty or null sub-agents list makes the flow meaningless and an IllegalArgumentException is thrown during graph building/config validation.

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-agentscope/src/main/java/com/alibaba/cloud/ai/agent/agentscope/flow/AgentScopeRoutingGraphBuildingStrategy.java:132

	@Override
	public KeyStrategyFactory generateKeyStrategyFactory(FlowGraphBuilder.FlowGraphConfig config) {
		KeyStrategyFactory parent = super.generateKeyStrategyFactory(config);
		return () -> {
			Map<String, com.alibaba.cloud.ai.graph.KeyStrategy> strategies = new HashMap<>(parent.apply());
			strategies.put(RoutingMergeNode.DEFAULT_MERGED_OUTPUT_KEY, new ReplaceStrategy());
			return strategies;
		};
	}

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

	private void validateAgentScopeRoutingConfig(FlowGraphBuilder.FlowGraphConfig config) {
		if (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {
			throw new IllegalArgumentException("AgentScope routing flow requires at least one sub-agent");
		}
		if (config.getCustomProperty("agentScopeModel") == null) {
			throw new IllegalArgumentException("AgentScope routing flow requires agentScopeModel in config custom properties");
		}
		if (!(config.getRootAgent() instanceof AgentScopeRoutingAgent)) {
			throw new IllegalArgumentException("AgentScope routing flow requires root agent to be AgentScopeRoutingAgent");
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add at least one sub-agent via builder/config before building the routing flow.
2. Check the code path that populates sub-agents — it may be conditional and skipped at runtime.
3. If dynamic, guard construction: only build the routing flow when subAgents is non-empty.

Example fix

// before
AgentScopeRoutingFlow.builder()
    .name("router")
    .model(model)
    .build(); // no sub-agents -> IllegalArgumentException
// after
AgentScopeRoutingFlow.builder()
    .name("router")
    .model(model)
    .subAgents(List.of(agentA, agentB))
    .build();

// Java: validate before building
if (subAgents == null || subAgents.isEmpty()) {
    throw new IllegalStateException("Routing flow requires at least one sub-agent before build()");
}

// Java
boolean hasSubAgents(java.util.Collection<?> subAgents) {
    return subAgents != null && !subAgents.isEmpty();
}

When it happens

Trigger: Building an AgentScope routing flow where FlowGraphConfig.getSubAgents() is null or empty — e.g. no .subAgents(...) calls on the builder, or sub-agents were filtered out before build.

Common situations: Forgot to register sub-agents on the routing builder; conditional code that adds sub-agents never executed; sub-agents list built dynamically and ended up empty; copying a routing example but omitting the sub-agent wiring.

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

• AgentScope Model must be provided for AgentScope routing age
• Routing sub-agents must be BaseAgent for merge support
• AgentScope routing flow requires agentScopeModel in config c
• AgentScope routing flow requires root agent to be AgentScope
• Version ID cannot be null

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