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

If maxConcurrency is set on a ParallelAgent builder, it must be >= 1; validate() rejects null-like misuse and any value below 1 (0, negative). maxConcurrency limits how many sub-agents run concurrently; only null (unlimited) or a positive value is accepted.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/ParallelAgent.java:267

			// Validate maximum sub-agent count for performance reasons
			if (subAgents.size() > 10) {
				throw new IllegalArgumentException(
						"ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: "
								+ subAgents.size());
			}

			// Validate that sub-agents have unique output keys to avoid conflicts during
			// result merging
			validateUniqueOutputKeys();

			// Validate input key compatibility
			validateInputKeyCompatibility();

			// Validate concurrency limit - allow maxConcurrency to be null (unlimited) or
			// within valid range
			if (maxConcurrency != null) {
				if (maxConcurrency < 1) {
					throw new IllegalArgumentException("maxConcurrency must be at least 1, but got: " + maxConcurrency);
				}
			}
		}

		/**
		 * Validates that all sub-agents have unique output keys.
		 */
		private void validateUniqueOutputKeys() {
			Set<String> outputKeys = new HashSet<>();
			Set<String> duplicateKeys = new HashSet<>();

			for (Agent subAgent : subAgents) {
				if (subAgent instanceof ReactAgent subReactAgent) {
					String outputKey = subReactAgent.getOutputKey();
					if (outputKey != null) {
						if (!outputKeys.add(outputKey)) {
							// This key was already seen, it's a duplicate
							duplicateKeys.add(outputKey);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a positive integer, e.g. maxConcurrency(2)
2. Fix the config/source so it yields >= 1, clamping: Math.max(1, value)
3. Omit maxConcurrency entirely (null) for unlimited concurrency

Example fix

// before
int concurrency = Integer.parseInt(props.getProperty("fanout.concurrency", "0"));
builder.maxConcurrency(concurrency);
// after
builder.maxConcurrency(Math.max(1, Integer.parseInt(props.getProperty("fanout.concurrency", "1"))));

int c = parseConcurrency(cfg); if (c < 1) c = 1; builder.maxConcurrency(c);

Integer safeConcurrency(Integer c) { return (c == null || c < 1) ? null : c; }

try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("maxConcurrency must be at least 1")) { /* clamp and rebuild */ } else throw e; }

When it happens

Trigger: ParallelAgent.builder()...maxConcurrency(0).build() or maxConcurrency(-1), typically when maxConcurrency is computed from config or a ratio that evaluated to 0.

Common situations: Reading a concurrency limit from properties where the key is missing and defaults to 0; computing concurrency from a percentage that rounds down to 0.

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

• ${type} requires 'name' field
• maxDelay must be greater than or equal to 0.
• The backoffMultiplier must be >= 1.0
• maxAttempts must be >= 1
• INVALID_PARAMS

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