alibaba/spring-ai-alibaba · error · IllegalArgumentException

maxConcurrency must be at least 1, but got:

Error message

maxConcurrency must be at least 1, but got: 

What it means

validateParallelConfig in ParallelGraphBuildingStrategy rejects FlowGraphConfig whose maxConcurrency is below 1 — the parallel execution pool would have no capacity, so the configuration is invalid before graph building.

Source

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

	private void validateParallelConfig(FlowGraphBuilder.FlowGraphConfig config) {
		if (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {
			throw new IllegalArgumentException("Parallel flow requires at least one sub-agent");
		}

		if (config.getSubAgents().size() < 2) {
			throw new IllegalArgumentException(
					"Parallel flow requires at least 2 sub-agents for meaningful parallel execution");
		}

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

		// Validate maxConcurrency if provided
		Integer maxConcurrency = (Integer) config.getCustomProperty("maxConcurrency");
		if (maxConcurrency != null && maxConcurrency < 1) {
			throw new IllegalArgumentException("maxConcurrency must be at least 1, but got: " + maxConcurrency);
		}
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set maxConcurrency to a positive integer (>= 1)
2. Omit the maxConcurrency property entirely to use the default
3. Validate the source value (config file/env) before assigning it

Example fix

// before
builder.customProperty("maxConcurrency", 0);
// after
builder.customProperty("maxConcurrency", Math.max(1, requestedConcurrency));

Integer mc = (Integer) config.getCustomProperty("maxConcurrency");
if (mc != null && mc < 1) {
    throw new IllegalArgumentException("maxConcurrency must be >= 1, got: " + mc);
}

static Integer sanitizeConcurrency(Integer mc) { return (mc == null || mc < 1) ? null : mc; }

When it happens

Trigger: config.customProperty("maxConcurrency", 0) or a negative/invalid value computed at runtime, passed to a ParallelAgent/FlowGraphBuilder config, then validateParallelConfig runs.

Common situations: Computing concurrency from a config file or env var that parses to 0 or -1; defaulting an unset variable to 0; typo passing wrong variable.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Parallel flow requires root agent to be a FlowAgent
• Routing flow requires at least one sub-agent
• Routing flow requires root agent to be a FlowAgent
• Sequential flow requires at least one sub-agent
• Sequential 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/e9a272b12b09ddc8. Report an issue: GitHub.