alibaba/spring-ai-alibaba · error · IllegalArgumentException

Loop flow requires exactly one sub-agent. Got: 0

Error message

Loop flow requires exactly one sub-agent. Got: 0

What it means

Thrown by LoopGraphBuildingStrategy.validateConfig when the config's sub-agents list is null or does not contain exactly one agent. A loop flow wraps a single sub-agent that is executed repeatedly until the LoopStrategy stops it; zero or multiple sub-agents are invalid. The message reports the actual count.

Source

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

	 * - Loop strategy must be provided and be an instance of LoopStrategy
	 * - Exactly one sub-agent must be provided (loops execute a single agent repeatedly)
	 */
	@Override
	public void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {
		super.validateConfig(config);

		// Validate loop strategy
		Object loopStrategyObj = config.getCustomProperty(LoopAgent.LOOP_STRATEGY);
		if (!(loopStrategyObj instanceof LoopStrategy)) {
			throw new IllegalArgumentException(
					"Loop flow requires a valid LoopStrategy. Got: " + (loopStrategyObj != null
							? loopStrategyObj.getClass().getName() : "null"));
		}

		// Validate sub-agent count
		List<Agent> subAgents = config.getSubAgents();
		if (subAgents == null || subAgents.size() != 1) {
			throw new IllegalArgumentException(
					"Loop flow requires exactly one sub-agent. Got: " + (subAgents != null ? subAgents.size() : 0));
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

  1. Add exactly one sub-agent to the loop flow, e.g. new LoopAgent(...).subAgent(worker).
  2. If multiple agents should run repeatedly, wrap them in a single SequentialAgent and use that as the loop's one sub-agent.
  3. Use ParallelGraphBuildingStrategy/SequentialAgent instead if the intent is not iteration over one agent.

Example fix

// before
new LoopAgent("loop")
    .subAgent(a)
    .subAgent(b); // 2 sub-agents
// after
new LoopAgent("loop")
    .subAgent(new SequentialAgent("body").subAgent(a).subAgent(b));
Defensive patterns

Strategy: validation

When it happens

Trigger: Building a loop flow with no sub-agents added; calling subAgents(a, b) with two or more agents on a LoopAgent; the sub-agent list passed as null; mistakenly using loop strategy for what should be a parallel or sequential flow.

Common situations: Forgot to add the looped agent; refactored a sequential agent into a loop but kept multiple sub-agents; generic builder code shared across flow types passing the same multi-agent list.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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