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

LatestCheckpointCache is a per-thread LRU cache of the latest checkpoints. maxCachedThreads counts thread entries; 0 disables caching. A negative value is rejected in the constructor with IllegalArgumentException.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/common/LatestCheckpointCache.java:42

/**
 * A bounded LRU cache that stores the latest checkpoint for each thread.
 */
public final class LatestCheckpointCache {

	private final int maxCachedThreads;

	private final Map<String, Checkpoint> checkpoints;

	/**
	 * Creates a latest-checkpoint cache with an LRU thread limit.
	 *
	 * @param maxCachedThreads maximum number of thread entries to keep, or 0 to
	 * disable caching
	 */
	public LatestCheckpointCache(int maxCachedThreads) {
		if (maxCachedThreads < 0) {
			throw new IllegalArgumentException("maxCachedThreads must be greater than or equal to 0");
		}
		this.maxCachedThreads = maxCachedThreads;
		this.checkpoints = createCache(maxCachedThreads);
	}

	/**
	 * Gets the cached latest checkpoint for a thread.
	 *
	 * @param threadId thread name/id used by the owning saver
	 * @return cached checkpoint when caching is enabled and the thread is present
	 */
	public synchronized Optional<Checkpoint> get(String threadId) {
		if (maxCachedThreads == 0) {
			return Optional.empty();
		}
		return Optional.ofNullable(checkpoints.get(threadId));
	}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass 0 to disable caching, or a positive thread-count
2. Clamp or validate the configured value before constructing the cache
3. Fix upstream config parsing that produced a negative number

Example fix

// before
new LatestCheckpointCache(config.getCacheSize()); // -1 from config
// after
int size = Math.max(0, config.getCacheSize());
new LatestCheckpointCache(size);

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

Integer sanitize(Integer v) { return v == null || v < 0 ? 0 : v; }

try { new LatestCheckpointCache(n); } catch (IllegalArgumentException e) { /* fall back to 0 */ }

When it happens

Trigger: new LatestCheckpointCache(-1) or any negative capacity, directly or via a saver builder passing a negative cache-size setting.

Common situations: Misreading the semantics of the parameter (thinking it's a timeout or byte size) or computing it from config where a negative/invalid default slipped in.

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

• maxCacheSize must be positive
• targetFolder '%s' must be a directory
• INVALID_PARAMS
• Oauth2UserNotFound
• InvalidParameter

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