spring-projects/spring-ai · error · IllegalStateException

Either vectorStore or jedisClient must be provided

Error message

Either vectorStore or jedisClient must be provided

What it means

DefaultSemanticCache.Builder.build() requires at least one of a pre-built vectorStore or a raw jedisClient. If neither is set, it cannot construct the backing RedisVectorStore and throws IllegalStateException 'Either vectorStore or jedisClient must be provided'. This is builder-time configuration validation, failing fast before the cache is used.

Source

Thrown at vector-stores/spring-ai-redis-semantic-cache/src/main/java/org/springframework/ai/vectorstore/redis/cache/semantic/DefaultSemanticCache.java:533

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

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

		public Builder jedisClient(RedisClient jedisClient) {
			this.jedisClient = jedisClient;
			return this;
		}

		public DefaultSemanticCache build() {
			if (this.vectorStore == null) {
				if (this.jedisClient == null) {
					throw new IllegalStateException("Either vectorStore or jedisClient must be provided");
				}
				if (this.embeddingModel == null) {
					throw new IllegalStateException("EmbeddingModel must be provided");
				}
				this.vectorStore = RedisVectorStore.builder(this.jedisClient, this.embeddingModel)
					.indexName(this.indexName)
					.prefix(this.prefix)
					.metadataFields(MetadataField.text("response"), MetadataField.text("response_text"),
							MetadataField.numeric("ttl"), MetadataField.tag("context_hash"))
					.initializeSchema(true)
					.build();
				if (this.vectorStore instanceof RedisVectorStore redisStore) {
					redisStore.afterPropertiesSet();
				}
			}
			return new DefaultSemanticCache(this.vectorStore, this.similarityThreshold, this.indexName, this.prefix,
					this.useDistanceThreshold);
		}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Provide a JedisClient: DefaultSemanticCache.builder().jedisClient(jedis)...
2. Or provide an already-configured RedisVectorStore via .vectorStore(redisVectorStore)
3. Ensure the Jedis bean is injected and non-null where the builder is invoked
4. Fail fast in your own config with a clear message if the connection bean is missing

Example fix

// before
DefaultSemanticCache.builder().build();
// after
DefaultSemanticCache.builder().jedisClient(jedisPooled).embeddingModel(model).build();

if (jedisClient == null && vectorStore == null) throw new IllegalStateException("Provide either jedisClient or vectorStore to DefaultSemanticCache.builder()");

static boolean canBuild(DefaultSemanticCache.Builder b) { return b != null; } // ensure dependencies injected before building

try { cache = DefaultSemanticCache.builder().build(); } catch (IllegalStateException e) { /* fail startup with actionable message */ }

When it happens

Trigger: Calling DefaultSemanticCache.builder().build() without ever calling .vectorStore(...) or .jedisClient(...) on the builder.

Common situations: Copy-pasting builder code and omitting the Redis connection; constructing the cache in a context where the Jedis bean was not injected (null dependency).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• EmbeddingModel must be provided
• Only outputType or outputJsonSchema can be set, not both.
• argumentType is required
• MessageEndpoint must be set
• DataSource must be set (either via dataSource() or jdbcTempl

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/21052894b4236539. Report an issue: GitHub.