alibaba/spring-ai-alibaba · error · IllegalArgumentException

Loop flow requires a valid LoopStrategy. Got: null

Error message

Loop flow requires a valid LoopStrategy. Got: null

What it means

Thrown by LoopGraphBuildingStrategy.validateConfig when the FlowGraphConfig's custom property LOOP_STRATEGY is not an instance of LoopStrategy (including when absent, i.e. null). A loop flow needs a concrete LoopStrategy to decide when to stop iterating; anything else makes the graph unbuildable. The message includes the actual class name or 'null' to pinpoint the mismatch.

Source

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

			return Stream.of(baseStrategies, loopStrategies)
					.flatMap(map -> map.entrySet().stream())
					.collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue, (k1, k2) -> k1));
		};
	}

	/**
	 * Validates loop-specific configuration requirements.
	 * - 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. Set a LoopStrategy implementation, e.g. config.addCustomProperty(LoopAgent.LOOP_STRATEGY, new MaxIterationsLoopStrategy(n)) or the builder API equivalent.
2. If you have custom logic, implement the LoopStrategy interface and register it under the LOOP_STRATEGY key.
3. Verify the property key matches LoopAgent.LOOP_STRATEGY exactly and is added to the FlowGraphConfig used for building.

Example fix

// before
FlowGraphConfig config = new FlowGraphConfig(); // no LOOP_STRATEGY set
loopStrategy.validateConfig(config);
// after
config.addCustomProperty(LoopAgent.LOOP_STRATEGY, new MaxIterationsLoopStrategy(5));
loopStrategy.validateConfig(config);

When it happens

Trigger: Building a LoopAgent/loop flow without setting config custom property LoopAgent.LOOP_STRATEGY; setting LOOP_STRATEGY to an object of the wrong class (e.g. a plain Integer count or a custom class not implementing LoopStrategy); property set under a different key than LoopAgent.LOOP_STRATEGY.

Common situations: Copy-pasted loop agent config that omitted the loop strategy; API change replaced an int max-iterations config with a LoopStrategy implementation; custom stopping logic implemented without implementing the LoopStrategy interface.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Loop flow requires exactly one sub-agent. Got: 0
• LoopAgent must have only one subAgent, please use subAgent()
• LoopAgent must have a loopStrategy.
• Sub-agents must be BaseAgent
• Parallel flow requires at least one sub-agent

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