alibaba/spring-ai-alibaba · error · IllegalArgumentException

maxCachedThreads must be greater than or equal to 0

Error message

maxCachedThreads must be greater than or equal to 0

What it means

OracleSaver.Builder.maxCachedThreads validates that the configured thread-cache size is non-negative; a negative value throws IllegalArgumentException('maxCachedThreads must be greater than or equal to 0'). A value of 0 disables the cache, so any negative number is meaningless and rejected at build time.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/oracle/OracleSaver.java:633

		 * Sets the state serializer
		 *
		 * @param stateSerializer the state serializer
		 * @return this builder
		 */
		public Builder stateSerializer(StateSerializer stateSerializer) {
			this.stateSerializer = stateSerializer;
			return this;
		}

		/**
		 * Sets the maximum number of latest checkpoints retained in memory.
		 *
		 * @param maxCachedThreads max cached threads, or 0 to disable the cache
		 * @return this builder
		 */
		public Builder maxCachedThreads(int maxCachedThreads) {
			if (maxCachedThreads < 0) {
				throw new IllegalArgumentException("maxCachedThreads must be greater than or equal to 0");
			}
			this.maxCachedThreads = maxCachedThreads;
			return this;
		}

		/**
		 * Creates a new instance of OracleSaver
		 *
		 * @return the new instance of OracleSaver.
		 */
		public OracleSaver build() {
			Objects.requireNonNull(dataSource, "dataSource cannot be null");
			if (stateSerializer == null) {
				this.stateSerializer = StateGraph.DEFAULT_JACKSON_SERIALIZER;
			}
			return new OracleSaver(this);
		}
	}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a value >= 0; use 0 to disable the thread cache.
2. Clamp the value before setting: Math.max(0, configuredValue).
3. Fix the source config/formula that produced a negative number.

Example fix

// before
int threads = config.getMaxThreads() - reserved;
builder.maxCachedThreads(threads); // throws if negative
// after
builder.maxCachedThreads(Math.max(0, config.getMaxThreads() - reserved));

// Java: validate before calling builder
if (configuredThreads < 0) {
    throw new ConfigurationException("maxCachedThreads must be >= 0, got " + configuredThreads);
}
builder.maxCachedThreads(configuredThreads);

try {
    builder.maxCachedThreads(threads);
} catch (IllegalArgumentException e) {
    builder.maxCachedThreads(0); // fall back to disabled cache
}

When it happens

Trigger: Calling OracleSaver.Builder.maxCachedThreads(-1) (or any negative int) before build().

Common situations: Computing the cache size from a config value or formula that can go negative (e.g. maxThreads - overhead) and passing it unvalidated.

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

• maxCachedThreads must be greater than or equal to 0
• Version ID cannot be null
• 模型配置不能为空
• Name must be provided
• Description must be provided

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