alibaba/spring-ai-alibaba · error · IllegalArgumentException

Parallel flow requires root agent to be a FlowAgent

Error message

Parallel flow requires root agent to be a FlowAgent

What it means

ParallelGraphBuildingStrategy requires the configured root agent to be an instance of FlowAgent so it can access the input key used to fan out sub-agent execution. Throwing IllegalArgumentException when config.getRootAgent() is not a FlowAgent.

Source

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

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

		if (config.getSubAgents().size() < 2) {
			throw new IllegalArgumentException(
					"Parallel flow requires at least 2 sub-agents for meaningful parallel execution");
		}

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

		// Validate maxConcurrency if provided
		Integer maxConcurrency = (Integer) config.getCustomProperty("maxConcurrency");
		if (maxConcurrency != null && maxConcurrency < 1) {
			throw new IllegalArgumentException("maxConcurrency must be at least 1, but got: " + maxConcurrency);
		}
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Make the root agent a FlowAgent subclass (e.g. ParallelAgent or another FlowAgent)
2. Check the agent factory/builder used to create the root and ensure it produces a FlowAgent
3. If a custom root is needed, extend FlowAgent so it exposes the input key

Example fix

// before
Agent root = new MyCustomAgent("root");
ParallelAgent.builder().rootAgent(root)...build();
// after
FlowAgent root = ParallelAgent.builder().subAgents(a, b).build();

if (!(config.getRootAgent() instanceof FlowAgent)) {
    throw new IllegalStateException("Parallel flow root must be a FlowAgent, got: " + config.getRootAgent().getClass().getName());
}

static boolean isValidParallelRoot(Agent a) { return a instanceof FlowAgent; }

When it happens

Trigger: Calling ParallelAgent/FlowGraphBuilder with a root agent that is a plain BaseAgent or custom Agent implementation rather than a FlowAgent subclass, then building the graph (buildCoreGraph or validateConfig).

Common situations: Passing a custom agent wrapper as the root of a parallel flow; composing flows where the root was created by a non-flow factory; refactoring that changed the root agent type.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• maxConcurrency must be at least 1, but got:
• Routing flow requires at least one sub-agent
• Routing flow requires root agent to be a FlowAgent
• Sequential flow requires at least one sub-agent
• Sequential 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/ce55ab762ab212c5. Report an issue: GitHub.