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

FileSystemSaver.Builder.maxCachedThreads sets how many threads' latest checkpoints are kept in memory (0 disables the cache). Negative values are rejected with IllegalArgumentException when the builder method is called.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/file/FileSystemSaver.java:442

		public Builder targetFolder(Path targetFolder) {
			this.targetFolder = targetFolder;
			return this;
		}

		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;
		}

		/**
		 * Builds a new FileSystemSaver instance.
		 * @return a new FileSystemSaver instance
		 * @throws IllegalArgumentException if targetFolder is null
		 */
		public FileSystemSaver build() {
			return new FileSystemSaver(this);
		}
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass 0 or a positive integer to maxCachedThreads
2. Validate/clamp the value read from configuration before applying it
3. Fix the config source emitting the negative value

Example fix

// before
builder.maxCachedThreads(props.getThreads()); // could be -5
// after
builder.maxCachedThreads(Math.max(0, props.getThreads()));

if (builderMaxCachedThreads < 0) throw new IllegalArgumentException("must be >= 0");

int clampNonNegative(int v) { return Math.max(0, v); }

try { builder.maxCachedThreads(v); } catch (IllegalArgumentException e) { builder.maxCachedThreads(0); }

When it happens

Trigger: fileSystemSaverBuilder.maxCachedThreads(-n) with any negative integer, often sourced from application configuration.

Common situations: Config file typo (negative number), or computing the value from an expression that can go negative under some environments.

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

• targetFolder '%s' must be a directory
• targetFolder '%s' cannot be created
• maxCachedThreads must be greater than or equal to 0
• Got error when creating files
• Got error when creating files

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