spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

MongoDBAtlasVectorStore.doDelete wraps any exception raised while deleting documents matching a filter expression into an IllegalStateException("Failed to delete documents by filter"). The MongoDB deleteMany call or the filter-expression conversion failed, so the deletion was not performed.

Source

Thrown at vector-stores/spring-ai-mongodb-atlas-store/src/main/java/org/springframework/ai/vectorstore/mongodb/atlas/MongoDBAtlasVectorStore.java:293

		Query query = new Query(org.springframework.data.mongodb.core.query.Criteria.where(ID_FIELD_NAME).in(idList));
		this.mongoTemplate.remove(query, this.collectionName);
	}

	@Override
	protected void doDelete(Filter.Expression filterExpression) {
		Assert.notNull(filterExpression, "Filter expression must not be null");

		try {
			String nativeFilterExpression = this.filterExpressionConverter.convertExpression(filterExpression);
			BasicQuery query = new BasicQuery(nativeFilterExpression);
			DeleteResult deleteResult = this.mongoTemplate.remove(query, this.collectionName);

			if (logger.isDebugEnabled()) {
				logger.debug("Deleted " + deleteResult.getDeletedCount() + " documents matching filter expression");
			}
		}
		catch (Exception e) {
			throw new IllegalStateException("Failed to delete documents by filter", e);
		}
	}

	@Override
	public List<Document> similaritySearch(String query) {
		return similaritySearch(SearchRequest.builder().query(query).build());
	}

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

		String nativeFilterExpressions = (request.getFilterExpression() != null)
				? this.filterExpressionConverter.convertExpression(request.getFilterExpression()) : "";

		float[] queryEmbedding = this.embeddingModel.embed(request.getQuery());
		var vectorSearch = new VectorSearchAggregation(EmbeddingUtils.toList(queryEmbedding), this.pathName,
				this.numCandidates, this.vectorIndexName, request.getTopK(), nativeFilterExpressions);

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Inspect the cause exception to see whether it is a converter error or a MongoDB driver error.
2. Simplify the filter to supported operators (EQ, IN, GT, etc.) — unsupported ops throw during conversion.
3. Verify MongoDB connectivity and that the configured database/collection exists.
4. Check the MongoDB user has delete permissions on the collection.
5. Retry the delete after transient connection issues.

Example fix

// before
vectorStore.delete("content LIKE 'foo%'");
// after
vectorStore.delete("category == 'foo'"); // supported operator

// ensure connectivity and supported filter ops before deleting
mongoClient.getDatabase(databaseName).runCommand(new Document("ping", 1)); // connectivity check
// and validate filter ops are EQ/NE/GT/GTE/LT/LTE/IN/NIN as in error 568

try {
    vectorStore.delete("category == 'foo'");
} catch (IllegalStateException e) {
    logger.error("Atlas delete failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
    // distinguish converter errors (unsupported op) from MongoDB driver errors
}

When it happens

Trigger: Calling vectorStore.delete(String filterExpression) or delete(Filter...) on MongoDBAtlasVectorStore when the Mongo deleteMany fails (invalid filter document, connection loss, unacknowledged write, collection dropped) or the Atlas converter throws on an unsupported operator.

Common situations: Malformed or unsupported filter expression (e.g. LIKE op producing an invalid Atlas filter doc); MongoDB connection pool exhausted; database/collection permissions missing delete rights; transient network failure.

Related errors

• Failed to delete documents by filter:
• Failed to delete documents by filter
• Not supported expression type:
• Unsupported operand type:
• Expression of type %s requires a left operand

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