spring-projects/spring-ai · error · IllegalStateException

'spring.ai.chat.client.tool-search-advisor.tool-index-type=v

Error message

'spring.ai.chat.client.tool-search-advisor.tool-index-type=vector' requires a VectorStore bean in the application context, but none was found. Add a VectorStore implementation (e.g. spring-ai-starter-vector-store-pgvector) to your dependencies.

What it means

ToolSearchAdvisorAutoConfiguration's VectorToolIndexConfiguration creates a VectorToolIndex bean that requires a VectorStore. When spring.ai.chat.client.tool-search-advisor.tool-index-type=vector is set but no VectorStore bean exists in the application context, the configuration fails fast with this IllegalStateException telling you to add a vector-store dependency.

Source

Thrown at auto-configurations/advisors/spring-ai-autoconfigure-tool-search-advisor/src/main/java/org/springframework/ai/chat/client/advisor/toolsearch/autoconfigure/ToolSearchAdvisorAutoConfiguration.java:177

	/**
	 * Registers a {@link VectorToolIndex}.
	 * <p>
	 * Activated only when {@code tool-index-type=vector} is set explicitly. Fails fast
	 * with a descriptive error if no {@link VectorStore} bean is present in the context.
	 */
	@Configuration(proxyBeanMethods = false)
	@ConditionalOnClass(VectorToolIndex.class)
	@ConditionalOnMissingBean(ToolIndex.class)
	@ConditionalOnProperty(prefix = ToolSearchAdvisorProperties.CONFIG_PREFIX, name = "tool-index-type",
			havingValue = "vector", matchIfMissing = false)
	static class VectorToolIndexConfiguration {

		@Bean
		VectorToolIndex vectorToolIndex(ObjectProvider<VectorStore> vectorStoreProvider) {
			VectorStore vectorStore = vectorStoreProvider.getIfAvailable();
			if (vectorStore == null) {
				throw new IllegalStateException(
						"'spring.ai.chat.client.tool-search-advisor.tool-index-type=vector' requires a VectorStore "
								+ "bean in the application context, but none was found. Add a VectorStore "
								+ "implementation (e.g. spring-ai-starter-vector-store-pgvector) to your "
								+ "dependencies.");
			}
			return new VectorToolIndex(vectorStore);
		}

	}

	/**
	 * Registers a {@link LuceneToolIndex}.
	 * <p>
	 * Activated only when {@code tool-index-type=lucene} is set explicitly. Also requires
	 * {@code LuceneToolIndex} on the classpath (i.e.
	 * {@code org.apache.lucene:lucene-core} present).
	 */
	@Configuration(proxyBeanMethods = false)

View on GitHub (pinned to 98a7beda4f)

Solutions

Add a vector store starter dependency, e.g. spring-ai-starter-vector-store-pgvector, and configure its connection properties.
Switch the property to the in-memory index: spring.ai.chat.client.tool-search-advisor.tool-index-type=in-memory, if a vector store is not needed.
Verify the VectorStore bean actually exists (actuator/beans or a debug breakpoint on vectorToolIndex) — a failed store auto-configuration also surfaces as 'none found'.

Example fix

# before
spring.ai.chat.client.tool-search-advisor.tool-index-type=vector

# after (no VectorStore available)
spring.ai.chat.client.tool-search-advisor.tool-index-type=in-memory
# or add:
# implementation 'org.springframework.ai:spring-ai-starter-vector-store-pgvector'

Defensive patterns

Strategy: validation

Validate before calling

// run before context startup or in a @PostConstruct
if (toolIndexType.equals("vector") && applicationContext.getBeanProvider(VectorStore.class).getIfAvailable() == null) {
    throw new IllegalStateException("tool-index-type=vector needs a VectorStore bean — add a vector store starter");
}

Try / catch

try {
    context = new SpringApplicationBuilder(App.class).run(args);
} catch (BeanCreationException e) {
    if (e.getMessage().contains("requires a VectorStore")) {
        // fall back to in-memory index or add a vector store dependency
    }
    throw e;
}

Prevention

Pair tool-index-type=vector with a vector-store starter dependency
Use in-memory index type when no vector DB is needed
Verify VectorStore auto-configuration is not excluded
Smoke-test application context startup in CI

When it happens

Trigger: Setting the property spring.ai.chat.client.tool-search-advisor.tool-index-type=vector (or leaving defaults that select vector) in a Spring Boot app that has no VectorStore bean, e.g. no spring-ai-starter-vector-store-* dependency or the store bean failed to register.

Common situations: Enabling the tool-search advisor's vector index in an application without any vector database configured; excluding the vector-store starter; the VectorStore auto-configuration being disabled by a @SpringBootApplication exclude or missing connection properties.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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