alibaba/spring-ai-alibaba · error · IllegalArgumentException

ParallelAgent requires at least 2 sub-agents for parallel ex

Error message

ParallelAgent requires at least 2 sub-agents for parallel execution, but got: 0

What it means

ParallelAgent requires at least 2 sub-agents to execute in parallel; validate() throws when subAgents is null or has fewer than 2 entries. With 0 or 1 sub-agents a parallel node is meaningless, so the builder refuses to construct it.

Source

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

		protected ParallelAgentBuilder self() {
			return this;
		}

		/**
		 * Validates the builder state before creating the agent.
		 * @throws IllegalArgumentException if validation fails
		 */
		@Override
		protected void validate() {
			// Validate name first (from parent)
			if (name == null || name.trim().isEmpty()) {
				throw new IllegalArgumentException("Name must be provided");
			}

			// Validate minimum sub-agent count for ParallelAgent (skip parent subAgents
			// check)
			if (subAgents == null || subAgents.size() < 2) {
				throw new IllegalArgumentException(
						"ParallelAgent requires at least 2 sub-agents for parallel execution, but got: "
								+ (subAgents != null ? subAgents.size() : 0));
			}

			// Validate maximum sub-agent count for performance reasons
			if (subAgents.size() > 10) {
				throw new IllegalArgumentException(
						"ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: "
								+ subAgents.size());
			}

			// Validate that sub-agents have unique output keys to avoid conflicts during
			// result merging
			validateUniqueOutputKeys();

			// Validate input key compatibility
			validateInputKeyCompatibility();

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass at least 2 sub-agents via .subAgents(agentA, agentB, ...)
2. Verify the sub-agent collection is populated before build(); if a single agent is all you need, use the agent directly or a different flow type
3. Add an upstream check that the filtered sub-agent list size >= 2

Example fix

// before
ParallelAgent.builder().name("p").subAgents(onlyAgent).build();
// after
if (agents.size() >= 2) {
    ParallelAgent.builder().name("p").subAgents(agents).build();
}

if (subAgents == null || subAgents.size() < 2) throw new IllegalArgumentException("ParallelAgent needs >= 2 sub-agents");

boolean canBuildParallel(java.util.List<Agent> a) { return a != null && a.size() >= 2; }

try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("requires at least 2 sub-agents")) { /* fall back to sequential or single agent */ } else throw e; }

When it happens

Trigger: ParallelAgent.builder().name("x").build() with no .subAgents(...) call, or with a list containing only one agent, or an empty/null list passed explicitly.

Common situations: Building the sub-agent list conditionally so all branches were filtered out; refactor changed a sequential agent to parallel but kept a single sub-agent; the sub-agent list is loaded from config and came back empty.

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

• At least one sub-agent must be provided for flow
• Name must be provided
• Description must be provided
• AgentCard or AgentCardProvider must be provided
• Name must be provided

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