alibaba/spring-ai-alibaba · error · IllegalArgumentException

Sub-agents must be provided

Error message

Sub-agents must be provided

What it means

ParallelAgent's builder validates in subAgents(List) that the list is non-null and non-empty; a parallel agent with nothing to run concurrently is meaningless, so it throws IllegalArgumentException. This is a fail-fast check performed when the builder method is called (and is exercised by the module's tests).

Source

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

		/**
		 * Sets the merge strategy for combining parallel execution results.
		 * @param mergeStrategy the strategy to use for merging results
		 * @return this builder instance for method chaining
		 */
		public ParallelAgentBuilder mergeStrategy(MergeStrategy mergeStrategy) {
			this.mergeStrategy = mergeStrategy;
			return this;
		}

		public ParallelAgentBuilder mergeOutputKey(String mergeOutputKey) {
			this.mergeOutputKey = mergeOutputKey;
			return this;
		}

		@Override
		public ParallelAgentBuilder subAgents(List<Agent> subAgents) {
			if (subAgents == null || subAgents.isEmpty()) {
				throw new IllegalArgumentException("Sub-agents must be provided");
			}
			if (subAgents.stream().anyMatch(agent -> !(agent instanceof BaseAgent))) {
				throw new IllegalArgumentException("Sub-agents must be BaseAgent");
			}
			return super.subAgents(subAgents);
		}

		/**
		 * Sets the maximum number of sub-agents that can execute concurrently.
		 * @param maxConcurrency the maximum concurrency limit
		 * @return this builder instance for method chaining
		 */
		public ParallelAgentBuilder maxConcurrency(Integer maxConcurrency) {
			this.maxConcurrency = maxConcurrency;
			return this;
		}

		/**

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure at least one sub-agent is created and passed before building the parallel agent.
2. Check upstream config/bean loading that produced an empty list and fail earlier with a clear message about which config key is empty.
3. If parallelism is optional in your flow, skip creating the ParallelAgent when the list is empty.

Example fix

// before
List<Agent> agents = loadSubAgents(); // may return empty
parallelBuilder.subAgents(agents); // throws: Sub-agents must be provided
// after
List<Agent> agents = loadSubAgents();
if (agents.isEmpty()) {
    throw new IllegalStateException("No sub-agents configured for parallelAgent");
}
parallelBuilder.subAgents(agents);

if (subAgents == null || subAgents.isEmpty()) {
    throw new IllegalStateException("parallelAgent requires at least one sub-agent");
}
parallelBuilder.subAgents(subAgents);

static boolean hasSubAgents(List<Agent> l) { return l != null && !l.isEmpty(); }

try {
    parallelBuilder.subAgents(agents);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Sub-agents must be provided")) {
        log.error("No sub-agents configured; check agent list source");
    }
}

When it happens

Trigger: Calling ParallelAgent.builder().subAgents(null), subAgents(List.of()), or subAgents(emptyList).

Common situations: Building sub-agent lists dynamically from config where the section is missing/empty; filtering a list down to zero agents before passing it; a wiring bug where the list field was never populated.

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

• SubAgent name is required
• SubAgent description is required
• SubAgent system prompt is required
• ChatModel must be provided for LLM routing agent
• LoopAgent must have a loopStrategy.

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