{"record":{"id":"553422eeceda7388","repo":"spring-projects/spring-ai","slug":"failed-to-initialize-chromavectorstore","errorCode":null,"errorMessage":"Failed to initialize ChromaVectorStore","messagePattern":"Failed to initialize ChromaVectorStore","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-chroma-store/src/main/java/org/springframework/ai/chroma/vectorstore/ChromaVectorStore.java","lineNumber":106,"sourceCode":"\t * @param builder {@link VectorStore.Builder} for chroma vector store\n\t */\n\tprotected ChromaVectorStore(Builder builder) {\n\t\tsuper(builder);\n\n\t\tthis.chromaApi = builder.chromaApi;\n\t\tthis.tenantName = builder.tenantName;\n\t\tthis.databaseName = builder.databaseName;\n\t\tthis.collectionName = builder.collectionName;\n\t\tthis.initializeSchema = builder.initializeSchema;\n\t\tthis.filterExpressionConverter = builder.filterExpressionConverter;\n\t\tthis.jsonMapper = JsonMapper.builder().addModules(JacksonUtils.instantiateAvailableModules()).build();\n\n\t\tif (builder.initializeImmediately) {\n\t\t\ttry {\n\t\t\t\tafterPropertiesSet();\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new IllegalStateException(\"Failed to initialize ChromaVectorStore\", e);\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic static Builder builder(ChromaApi chromaApi, EmbeddingModel embeddingModel) {\n\t\treturn new Builder(chromaApi, embeddingModel);\n\t}\n\n\t@Override\n\tpublic void afterPropertiesSet() throws Exception {\n\t\tif (!this.initialized) {\n\t\t\tvar collection = this.chromaApi.getCollection(this.tenantName, this.databaseName, this.collectionName);\n\t\t\tif (collection == null) {\n\t\t\t\tif (this.initializeSchema) {\n\t\t\t\t\tvar tenant = this.chromaApi.getTenant(this.tenantName);\n\t\t\t\t\tif (tenant == null) {\n\t\t\t\t\t\tthis.chromaApi.createTenant(this.tenantName);\n\t\t\t\t\t}","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-chroma-store/src/main/java/org/springframework/ai/chroma/vectorstore/ChromaVectorStore.java#L88-L124","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the cause chain for the root HTTP/connection error from Chroma; fix connectivity (host, port, auth).","Verify the tenant and database exist (or use Chroma defaults: 'default' tenant / 'default_database').","Disable eager initialization (don't set initializeImmediately / let afterPropertiesSet run lazily) and start Chroma first.","Ensure initializeSchema=true if you expect the collection to be auto-created."],"exampleFix":"// before: eager init against a server that isn't up\nChromaVectorStore.builder(chromaApi, embeddingModel).initializeImmediately(true).build();\n// after: lazy init + verify server first\n// curl http://localhost:8000/api/v1/heartbeat\nChromaVectorStore.builder(chromaApi, embeddingModel).initializeSchema(true).build();","handlingStrategy":"try-catch","validationCode":"// verify Chroma is reachable before constructing the store\nHttpGet hb = new HttpGet(chromaBaseUrl + \"/api/v1/heartbeat\");\ntry (CloseableHttpResponse resp = client.execute(hb)) {\n  if (resp.getStatusLine().getStatusCode() != 200) throw new IllegalStateException(\"Chroma not ready\");\n}","typeGuard":"null","tryCatchPattern":"ChromaVectorStore store;\ntry {\n  store = ChromaVectorStore.builder(chromaApi, embeddingModel).initializeImmediately(true).build();\n} catch (IllegalStateException e) {\n  throw new IllegalStateException(\"Chroma init failed — check server, tenant/database\", e.getCause());\n}","preventionTips":["Use a health-check/readiness gate so the app only boots after Chroma responds.","Confirm tenant ('default') and database ('default_database') names exist on the server.","Avoid initializeImmediately(true) in environments where Chroma starts in parallel.","Check auth token configuration if Chroma runs with authentication enabled."],"tags":["chroma","initialization","vector-store","http","state-exception"],"backgroundTag":"module-init-failed","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}