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

Builder.maxCachedThreads validates that the in-memory checkpoint cache size is non-negative; passing a negative value throws this IllegalArgumentException immediately at builder time. 0 is allowed and disables the cache.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/postgresql/PostgresSaver.java:636

		private DataSource datasource;

		// New CreateOption field with default value
		private CreateOption createOption = CreateOption.CREATE_IF_NOT_EXISTS;

		private int maxCachedThreads = 1024;

		// Legacy fields for backward compatibility
		private boolean createTables;
		private boolean dropTablesFirst;

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

		public Builder stateSerializer(StateSerializer stateSerializer) {
			this.stateSerializer = stateSerializer;
			return this;
		}

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

		public Builder port(Integer port) {
			this.port = port;
			return this;

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a value >= 0; use 0 to explicitly disable the cache.
2. Clamp or sanitize external config before passing: Math.max(0, configuredValue).
3. Fix the configuration source (env var / application.properties) supplying the negative number.

Example fix

// before
builder.maxCachedThreads(Integer.parseInt(env.get("CACHE_SIZE"))); // -1 possible
// after
int cacheSize = Math.max(0, Integer.parseInt(env.getOrDefault("CACHE_SIZE", "0")));
builder.maxCachedThreads(cacheSize);

int v = Integer.parseInt(cfg.get("cacheSize"));
if (v < 0) throw new IllegalArgumentException("cacheSize must be >= 0");
builder.maxCachedThreads(v);

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

When it happens

Trigger: PostgresSaver.builder().maxCachedThreads(-1) or computing the value from config (e.g. env var or properties) that yields a negative number.

Common situations: Misconfigured property like 'checkpoint.cache-size=-10'; sign error when computing 'max - used'; unparsed/default sentinel values like -1 meaning 'unlimited'.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• SkillRegistry must be provided. Use FileSystemSkillRegistry.
• At least one limit must be specified (threadLimit or runLimi
• Multiple savers configured, but no specific one requested.
• maxCachedThreads must be greater than or equal to 0
• '%s' cannot be blank

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