alibaba/spring-ai-alibaba · error · IllegalArgumentException

maxParallelTools must be at least 1

Error message

maxParallelTools must be at least 1

What it means

AgentToolNode.Builder.maxParallelTools(int) sets the concurrency limit for parallel tool execution; a value below 1 would deadlock or never run any tool, so the builder throws IllegalArgumentException when max < 1. Default is 5.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/node/AgentToolNode.java:932

		 * execute concurrently up to {@link #maxParallelTools} limit.
		 * @param parallel true to enable parallel execution
		 * @return this builder
		 */
		public Builder parallelToolExecution(boolean parallel) {
			this.parallelToolExecution = parallel;
			return this;
		}

		/**
		 * Set the maximum number of tools to execute in parallel. This limits concurrent
		 * tool executions to prevent resource exhaustion.
		 * @param max the maximum parallel tools (default: 5)
		 * @return this builder
		 * @throws IllegalArgumentException if max is less than 1
		 */
		public Builder maxParallelTools(int max) {
			if (max < 1) {
				throw new IllegalArgumentException("maxParallelTools must be at least 1");
			}
			this.maxParallelTools = max;
			return this;
		}

		/**
		 * Set the timeout for each tool execution.
		 * @param timeout the timeout duration (default: 5 minutes)
		 * @return this builder
		 */
		public Builder toolExecutionTimeout(Duration timeout) {
			this.toolExecutionTimeout = timeout;
			return this;
		}

		/**
		 * Enable automatic wrapping of synchronous tools as async.
		 *

View on GitHub (pinned to f82da0b50f)

Solutions

1. Use maxParallelTools(1) to run tools sequentially
2. Provide a positive value, e.g. maxParallelTools(5)
3. Clamp/validate config before building: max = Math.max(1, configured)

Example fix

// before
AgentToolNode.builder().maxParallelTools(0).build();
// after
AgentToolNode.builder().maxParallelTools(Math.max(1, configuredLimit)).build();

if (maxParallelTools < 1) throw new IllegalArgumentException("maxParallelTools must be >= 1");

int safeParallelism(Integer cfg) { return (cfg == null || cfg < 1) ? 5 : cfg; }

try { b.maxParallelTools(n); } catch (IllegalArgumentException e) { b.maxParallelTools(5); log.warn("Reset maxParallelTools to default"); }

When it happens

Trigger: Calling AgentToolNode.builder().maxParallelTools(0) or a negative value.

Common situations: maxParallelTools loaded from config where 0 or unset is the default; computing the limit from available CPUs or a quota that evaluated to 0; disabling parallelism with 0 instead of using 1 (sequential).

Related errors

• At least one fallback model must be specified
• maxRetries must be >= 0
• maxTools must be > 0
• Elastic search index name must be provided
• Param Not Support Object

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