alibaba/spring-ai-alibaba · error · IllegalArgumentException

At least one sub-agent must be provided for flow

Error message

At least one sub-agent must be provided for flow

What it means

FlowAgentBuilder.validate() throws when no sub-agents were provided: a flow agent by definition routes work through at least one child agent, so an empty or null subAgents list makes the flow meaningless and build() is aborted.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/builder/FlowAgentBuilder.java:180

	/**
	 * Returns the concrete builder instance. This method enables fluent interface support
	 * in subclasses.
	 * @return this builder instance
	 */
	protected abstract B self();

	/**
	 * Validates the builder state before creating the agent. Subclasses can override this
	 * method to add specific validation logic.
	 * @throws IllegalArgumentException if validation fails
	 */
	protected void validate() {
		if (name == null || name.trim().isEmpty()) {
			throw new IllegalArgumentException("Name must be provided");
		}
		if (subAgents == null || subAgents.isEmpty()) {
			throw new IllegalArgumentException("At least one sub-agent must be provided for flow");
		}
	}

	/**
	 * Builds the concrete FlowAgent instance. Subclasses must implement this method to
	 * create the specific agent type.
	 * @return the built FlowAgent instance
	 * @throws GraphStateException if agent creation fails
	 */
	public T build() {
		if (this.saver != null) {
			if (this.compileConfig == null) {
				this.compileConfig = CompileConfig.builder().saverConfig(SaverConfig.builder().register(saver).build()).build();
			}
			this.compileConfig = CompileConfig.builder(compileConfig).saverConfig(SaverConfig.builder().register(saver).build()).build();
		}
		return doBuild();
	};

View on GitHub (pinned to f82da0b50f)

Solutions

1. Provide at least one (and per ParallelAgent, two) sub-agents via .subAgents(...)
2. Check why the sub-agent collection is empty before building; log and fail fast upstream
3. If no sub-agent is truly needed, use a plain LLM agent instead of a flow agent

Example fix

// before
if (!agents.isEmpty()) {} // agents was empty but build happened anyway
SequentialAgent.builder().name("p").subAgents(agents).build();
// after
if (!agents.isEmpty()) {
    SequentialAgent.builder().name("p").subAgents(agents).build();
}

if (subAgents == null || subAgents.isEmpty()) throw new IllegalArgumentException("Flow requires >= 1 sub-agent");

boolean hasSubAgents(java.util.List<Agent> a) { return a != null && !a.isEmpty(); }

try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("At least one sub-agent")) { /* register a default sub-agent */ } else throw e; }

When it happens

Trigger: Calling .build() on a flow agent builder without .subAgents(...), or passing an empty list (e.g. a conditionally populated list that ended up empty).

Common situations: Sub-agent list assembled from feature-flagged registrations that were all disabled; config-driven agent lists that parsed to empty; forgetting the subAgents call after refactoring.

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

• ParallelAgent requires at least 2 sub-agents for parallel ex
• Name must be provided
• Description must be provided
• AgentCard or AgentCardProvider must be provided
• Name must be provided

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