alibaba/spring-ai-alibaba · error · IllegalArgumentException

maxCacheSize must be positive

Error message

maxCacheSize must be positive

What it means

Builder.maxCacheSize validates that the fetched-page cache capacity is strictly positive; a non-positive value throws IllegalArgumentException. The tool caches fetched HTML by URL and rejects sizes that would make the cache unusable.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/WebFetchTool.java:441

		private Builder(ChatClient chatClient) {
			if (chatClient == null) {
				throw new IllegalArgumentException("ChatClient must not be null");
			}
			this.chatClient = chatClient;
		}

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

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

		public Builder maxRetries(int maxRetries) {
			if (maxRetries < 0) {
				throw new IllegalArgumentException("maxRetries must be non-negative");
			}
			this.maxRetries = maxRetries;
			return this;
		}

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

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a positive cache size, e.g. .maxCacheSize(100).
2. Omit the call to use the library default cache size.
3. Validate the configured value > 0 before building the tool.
4. If you want no caching behavior, check the tool's API for an explicit disable option instead of size 0.

Example fix

// before
.maxCacheSize(0)
// after
.maxCacheSize(128)

int size = properties.maxCacheSize();
if (size <= 0) {
    throw new IllegalArgumentException("webfetch.max-cache-size must be > 0, got " + size);
}

boolean isValidSize(int v) { return v > 0; }

try {
    builder.maxCacheSize(size);
} catch (IllegalArgumentException e) {
    log.warn("invalid maxCacheSize {}, using default", size);
    builder = WebFetchTool.builder(chatClient); // restart with defaults
}

When it happens

Trigger: Calling .maxCacheSize(0) or a negative number on the WebFetchTool Builder.

Common situations: Reading the cache size from a properties file that returns 0 when unset; experimental config disabling the cache with 0 (disabling is not supported via 0 — omit tuning instead); arithmetic producing a negative size.

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

• Name must be provided
• Description must be provided
• AgentCard or AgentCardProvider must be provided
• Name must be provided
• ParallelAgent requires at least 2 sub-agents for parallel ex

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