alibaba/spring-ai-alibaba · error · IllegalArgumentException

maxParallelTools must be at least 1

Error message

maxParallelTools must be at least 1

What it means

Builder.maxParallelTools(int) validates that the requested parallelism is at least 1 and throws IllegalArgumentException otherwise. Parallel tool execution must have a positive bound; 0 or negative values are meaningless.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/Builder.java:428

	 * @return this builder instance
	 */
	public Builder parallelToolExecution(boolean parallel) {
		this.parallelToolExecution = parallel;
		return this;
	}

	/**
	 * Sets the maximum number of tools that can execute in parallel.
	 * <p>
	 * This limit helps prevent resource exhaustion when many tools are
	 * called simultaneously. The default is 5.
	 * @param max the maximum number of parallel tool executions (must be at least 1)
	 * @return this builder instance
	 * @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;
	}

	/**
	 * Sets the timeout for individual tool executions.
	 * <p>
	 * If a tool execution exceeds this timeout, it will be cancelled and
	 * an error will be returned. The default is 5 minutes.
	 * @param timeout the maximum duration for a single tool execution
	 * @return this builder instance
	 * @throws NullPointerException if timeout is null
	 */
	public Builder toolExecutionTimeout(Duration timeout) {
		this.toolExecutionTimeout = Objects.requireNonNull(timeout, "timeout cannot be null");
		return this;
	}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a value >= 1 to maxParallelTools.
2. To disable parallel execution use a different mechanism (e.g. don't enable parallel tools) rather than maxParallelTools(0).
3. Clamp computed values: Math.max(1, configuredValue).

Example fix

// before
int max = Integer.parseInt(cfg.get("tool.parallelism")); // 0
builder.maxParallelTools(max);
// after
builder.maxParallelTools(Math.max(1, max));

if (configuredMaxParallelTools < 1) throw new IllegalArgumentException("maxParallelTools must be >= 1, got " + configuredMaxParallelTools);

try { builder.maxParallelTools(n); } catch (IllegalArgumentException e) { builder.maxParallelTools(1); }

When it happens

Trigger: Calling ReactAgent.builder().maxParallelTools(0) or maxParallelTools(-1) (or a computed value that became 0/negative) before build().

Common situations: Deriving parallelism from config (e.g. env var defaulting to 0), off-by-one in computed limits, or disabling parallel tools by setting 0 instead of omitting the setting.

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

• Agent name must not be empty
• Either chatClient or model must be provided
• Tool not found with id: <id>
• Unknown agent status code:
• Unknown agent type code:

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