alibaba/spring-ai-alibaba · error · IllegalArgumentException

Parallel flow requires at least 2 sub-agents for meaningful

Error message

Parallel flow requires at least 2 sub-agents for meaningful parallel execution

What it means

Thrown by ParallelGraphBuildingStrategy.validateParallelConfig when the config has exactly one sub-agent. While one sub-agent technically passes the non-empty check, the strategy rejects it because parallel execution of a single agent is meaningless overhead; at least two sub-agents are required for meaningful parallel fan-out.

Source

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

			if (hookStrategies != null && !hookStrategies.isEmpty()) {
				strategies.putAll(hookStrategies);
			}
		}
		return strategies;
	}

	/**
	 * 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. Add a second (or more) sub-agent so the parallel fan-out is meaningful.
2. If only one agent is needed, use a sequential/single-agent flow instead of parallel.
3. Guard the build: if subAgents.size() < 2, fall back to a different flow type.

Example fix

// before
new ParallelAgent("fanout").subAgent(agentA); // only 1
// after
new ParallelAgent("fanout")
    .subAgent(agentA)
    .subAgent(agentB);

if (config.getSubAgents() != null && config.getSubAgents().size() < 2) { throw new IllegalStateException("Parallel flow needs >= 2 sub-agents; use sequential otherwise"); }

try { parallelStrategy.validateConfig(config); } catch (IllegalArgumentException e) { log.warn("Falling back to sequential flow: {}", e.getMessage()); }

When it happens

Trigger: Building a parallel flow with exactly one subAgent(...) call; dynamic agent list ended up with one element after filtering; intended sequential behavior but chose parallel strategy.

Common situations: Config-driven assembly where only one worker was defined; code migrated from sequential to parallel without adding agents; tests reusing a single-agent fixture.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Parallel flow requires at least one sub-agent
• Loop flow requires exactly one sub-agent. Got: 0
• Sub-agents must be provided
• Sub-agents must be BaseAgent
• Loop flow requires a valid LoopStrategy. Got: null

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