alibaba/spring-ai-alibaba · error · IllegalArgumentException

maxTools must be > 0

Error message

maxTools must be > 0

What it means

ToolSelectionInterceptor.Builder.maxTools(int) requires a strictly positive value because it caps how many tools the selection model may pick; a zero or negative cap would make tool selection always produce nothing. IllegalArgumentException is thrown when maxTools <= 0.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/interceptor/toolselection/ToolSelectionInterceptor.java:222

	public static class Builder {
		private ChatModel selectionModel;
		private String systemPrompt = DEFAULT_SYSTEM_PROMPT;
		private Integer maxTools;
		private Set<String> alwaysInclude;

		public Builder selectionModel(ChatModel selectionModel) {
			this.selectionModel = selectionModel;
			return this;
		}

		public Builder systemPrompt(String systemPrompt) {
			this.systemPrompt = systemPrompt;
			return this;
		}

		public Builder maxTools(int maxTools) {
			if (maxTools <= 0) {
				throw new IllegalArgumentException("maxTools must be > 0");
			}
			this.maxTools = maxTools;
			return this;
		}

		public Builder alwaysInclude(Set<String> alwaysInclude) {
			this.alwaysInclude = alwaysInclude;
			return this;
		}

		public Builder alwaysInclude(String... toolNames) {
			this.alwaysInclude = new HashSet<>(Arrays.asList(toolNames));
			return this;
		}

		public ToolSelectionInterceptor build() {
			if (selectionModel == null) {
				throw new IllegalStateException("selectionModel is required");

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a positive integer, e.g. maxTools(3)
2. Guard the value before building: only call maxTools when the value is > 0, otherwise leave the default
3. If 0 means 'no limit', skip setting maxTools entirely instead of passing 0

Example fix

// before
ToolSelectionInterceptor.builder().maxTools(0).build();
// after
ToolSelectionInterceptor.builder().maxTools(3).build();

if (maxTools <= 0) throw new IllegalArgumentException("maxTools must be a positive integer");

boolean isValidToolCap(int n) { return n > 0; }

try { b.maxTools(n); } catch (IllegalArgumentException e) { log.warn("Ignoring invalid maxTools={}", n); }

When it happens

Trigger: Calling ToolSelectionInterceptor.Builder.maxTools(0) or maxTools(negative).

Common situations: maxTools read from config with a default of 0 meaning 'unset'; arithmetic that computes the cap (e.g. remaining budget) reaching 0 or below.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• At least one fallback model must be specified
• maxRetries must be >= 0
• selectionModel is required
• maxParallelTools must be at least 1
• Elastic search index name must be provided

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