alibaba/spring-ai-alibaba · error · IllegalArgumentException

Sequential flow requires at least one sub-agent

Error message

Sequential flow requires at least one sub-agent

What it means

Configuration validation failure in SequentialGraphBuildingStrategy.validateSequentialConfig. A sequential flow graph is defined by chaining its sub-agents in order; if FlowGraphConfig.getSubAgents() is null or empty there is nothing to chain, so building the graph would be meaningless and IllegalArgumentException is thrown during validation (invoked from validateConfig before buildCoreGraph). Callers must add at least one sub-agent to the flow config before building a sequential agent.

Source

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

	@Override
	public String getStrategyType() {
		return FlowAgentEnum.SEQUENTIAL.getType();
	}

	@Override
	public void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {
		super.validateConfig(config);
		validateSequentialConfig(config);
	}

	/**
	 * Validates sequential-specific configuration requirements.
	 * @param config the configuration to validate
	 * @throws IllegalArgumentException if validation fails
	 */
	private void validateSequentialConfig(FlowGraphBuilder.FlowGraphConfig config) {
		if (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {
			throw new IllegalArgumentException("Sequential flow requires at least one sub-agent");
		}

		// Ensure root agent is a FlowAgent for input key access
		if (!(config.getRootAgent() instanceof FlowAgent)) {
			throw new IllegalArgumentException("Sequential flow requires root agent to be a FlowAgent");
		}
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add at least one sub-agent via .subAgents(...)
2. Verify the code path that populates the agent list runs before build()
3. Guard with a check that subAgents is non-empty before building

Example fix

// before
SequentialAgent.builder().name("flow").build();
// after
SequentialAgent.builder().name("flow").subAgents(step1, step2).build();

if (subAgents == null || subAgents.isEmpty()) {
    throw new IllegalArgumentException("Sequential flow requires at least one sub-agent");
}

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

When it happens

Trigger: Building a SequentialAgent/sequential flow graph without registering any sub-agents before buildCoreGraph/validateConfig.

Common situations: Forgot .subAgents(...) on the builder; loop that appends agents never executed; agents list cleared by earlier code.

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

• Sequential flow requires root agent to be a FlowAgent
• Parallel flow requires root agent to be a FlowAgent
• maxConcurrency must be at least 1, but got:
• Routing flow requires at least one sub-agent
• Routing flow requires root agent to be a FlowAgent

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