alibaba/spring-ai-alibaba · error · IllegalArgumentException

Parallel flow requires at least one sub-agent

Error message

Parallel flow requires at least one sub-agent

What it means

Thrown by ParallelGraphBuildingStrategy.validateParallelConfig when the config's sub-agents list is null or empty. A parallel flow fans out work across multiple sub-agents, so at least one is mandatory for the graph to be built. This check runs before the stricter two-agent check (error 579).

Source

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

			return strategies;
		}
		for (Hook hook : hooks) {
			Map<String, KeyStrategy> hookStrategies = hook.getKeyStrategys();
			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 at least one (ideally two or more) sub-agent before building: parallelAgent.subAgent(a).subAgent(b).
2. Validate the source collection is non-empty before constructing the flow.
3. Use a different flow type if a single agent is all you have.

Example fix

// before
new ParallelAgent("fanout"); // no sub-agents
// after
new ParallelAgent("fanout")
    .subAgent(agentA)
    .subAgent(agentB);

When it happens

Trigger: Building a ParallelAgent/parallel flow without calling subAgent(...) at all; the sub-agents list passed as null; agent-collection field never populated before build.

Common situations: Dynamically assembling sub-agents from config where the source list was empty; forgot to add agents; a filtering step removed all candidates before build.

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

• Parallel flow requires at least 2 sub-agents for meaningful
• 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/670d2b5db4f2ee28. Report an issue: GitHub.