spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

ChromaVectorStore.doDelete wraps filter-based deletion in a try/catch and rethrows any exception as IllegalStateException("Failed to delete documents by filter", e). The underlying Chroma delete request (converting the filter and calling the delete API) failed.

Source

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

		try {
			ChromaFilterExpressionConverter converter = new ChromaFilterExpressionConverter();
			String whereClauseStr = converter.convertExpression(expression);

			Map<String, Object> whereClause = this.chromaApi.where(whereClauseStr);

			if (logger.isDebugEnabled()) {
				logger.debug("Deleting with where clause: " + whereClause);
			}

			DeleteEmbeddingsRequest deleteRequest = new DeleteEmbeddingsRequest(null, whereClause);
			this.chromaApi.deleteEmbeddings(this.tenantName, this.databaseName, this.requireCollectionId(),
					deleteRequest);
		}
		catch (Exception e) {
			if (logger.isErrorEnabled()) {
				logger.error("Failed to delete documents by filter: " + e.getMessage(), e);
			}
			throw new IllegalStateException("Failed to delete documents by filter", e);
		}
	}

	@Override
	public List<Document> doSimilaritySearch(SearchRequest request) {

		String query = request.getQuery();
		Assert.notNull(query, "Query string must not be null");

		float[] embedding = this.embeddingModel.embed(query);

		Map<String, Object> where = (request.getFilterExpression() != null)
				? jsonToMap(this.filterExpressionConverter.convertExpression(request.getFilterExpression())) : null;

		var queryRequest = new ChromaApi.QueryRequest(embedding, request.getTopK(), where);
		var queryResponse = this.chromaApi.queryCollection(this.tenantName, this.databaseName,
				this.requireCollectionId(), queryRequest);
		var embeddings = this.chromaApi.toEmbeddingResponseList(queryResponse);

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Inspect the cause/cause message logged with the error to find the actual Chroma API failure.
2. Verify Chroma server availability and authentication; re-run initialization to refresh the collection ID.
3. Simplify the filter to a plain equality where-clause to rule out converter output problems.
4. Retry the delete once connectivity is restored — the failure aborts before data is deleted only if the request failed.

Example fix

// before: filter referencing a metadata key with a type Chroma rejects
vectorStore.delete(Filter.expr("score").gt("high"));
// after: use correct value type for the metadata
vectorStore.delete(Filter.expr("score").gt(0.5));

// ensure collection id is still valid before delete
try { chromaApi.count(collectionId, null); } catch (Exception e) { reinitializeStore(); }

null

try {
  vectorStore.delete(filterExpression);
} catch (IllegalStateException e) {
  logger.error("Chroma delete failed", e.getCause());
  // optionally rebuild the store to refresh collectionId, then retry once
}

When it happens

Trigger: Calling vectorStore.delete(Filter) when the Chroma server returns an error (connection failure, HTTP error, invalid filter payload, unknown collection id) during the delete request.

Common situations: Chroma server restarted or unreachable; the collection ID cached at initialization no longer exists; a filter expression that the converter translated into something Chroma's where-clause rejects; auth failure.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Failed to delete documents by filter
• Failed to initialize ChromaVectorStore
• Failed to delete documents by filter
• Failed to delete nodes by filter
• Error removing embedding: ${e.getMessage()}

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