spring-projects/spring-ai · error · IllegalStateException

Failed to initialize ChromaVectorStore

Error message

Failed to initialize ChromaVectorStore

What it means

ChromaVectorStore's builder can initialize immediately in the constructor (initializeImmediately). If afterPropertiesSet() (collection lookup/creation) throws for any reason, the constructor wraps it in this IllegalStateException. The Chroma server or the configured tenant/database/collection was not reachable or did not behave as expected.

Source

Thrown at vector-stores/spring-ai-chroma-store/src/main/java/org/springframework/ai/chroma/vectorstore/ChromaVectorStore.java:106

	 * @param builder {@link VectorStore.Builder} for chroma vector store
	 */
	protected ChromaVectorStore(Builder builder) {
		super(builder);

		this.chromaApi = builder.chromaApi;
		this.tenantName = builder.tenantName;
		this.databaseName = builder.databaseName;
		this.collectionName = builder.collectionName;
		this.initializeSchema = builder.initializeSchema;
		this.filterExpressionConverter = builder.filterExpressionConverter;
		this.jsonMapper = JsonMapper.builder().addModules(JacksonUtils.instantiateAvailableModules()).build();

		if (builder.initializeImmediately) {
			try {
				afterPropertiesSet();
			}
			catch (Exception e) {
				throw new IllegalStateException("Failed to initialize ChromaVectorStore", e);
			}
		}
	}

	public static Builder builder(ChromaApi chromaApi, EmbeddingModel embeddingModel) {
		return new Builder(chromaApi, embeddingModel);
	}

	@Override
	public void afterPropertiesSet() throws Exception {
		if (!this.initialized) {
			var collection = this.chromaApi.getCollection(this.tenantName, this.databaseName, this.collectionName);
			if (collection == null) {
				if (this.initializeSchema) {
					var tenant = this.chromaApi.getTenant(this.tenantName);
					if (tenant == null) {
						this.chromaApi.createTenant(this.tenantName);
					}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Check the cause chain for the root HTTP/connection error from Chroma; fix connectivity (host, port, auth).
2. Verify the tenant and database exist (or use Chroma defaults: 'default' tenant / 'default_database').
3. Disable eager initialization (don't set initializeImmediately / let afterPropertiesSet run lazily) and start Chroma first.
4. Ensure initializeSchema=true if you expect the collection to be auto-created.

Example fix

// before: eager init against a server that isn't up
ChromaVectorStore.builder(chromaApi, embeddingModel).initializeImmediately(true).build();
// after: lazy init + verify server first
// curl http://localhost:8000/api/v1/heartbeat
ChromaVectorStore.builder(chromaApi, embeddingModel).initializeSchema(true).build();

// verify Chroma is reachable before constructing the store
HttpGet hb = new HttpGet(chromaBaseUrl + "/api/v1/heartbeat");
try (CloseableHttpResponse resp = client.execute(hb)) {
  if (resp.getStatusLine().getStatusCode() != 200) throw new IllegalStateException("Chroma not ready");
}

null

ChromaVectorStore store;
try {
  store = ChromaVectorStore.builder(chromaApi, embeddingModel).initializeImmediately(true).build();
} catch (IllegalStateException e) {
  throw new IllegalStateException("Chroma init failed — check server, tenant/database", e.getCause());
}

When it happens

Trigger: Building ChromaVectorStore with the builder flag that forces immediate initialization while the Chroma server is down, the tenant/database doesn't exist, authentication fails, or the API returns an error.

Common situations: Chroma not yet started when the Spring context boots; wrong host/port in ChromaApi base URL; tenant/database names that don't exist on the server; auth token mismatch.

Related errors

• Collection {collectionName} with the tenant: {tenantName} an
• Failed to delete documents by filter
• Failed to delete documents by filter
• Index %s does not exist in table %s
• Unexpected value: {expressionType}

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