spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

CouchbaseSearchVectorStore.doDelete(Filter.Expression) runs a N1QL DELETE query on the scope and wraps any exception (query syntax error, connectivity failure, index missing, timeouts) in IllegalStateException. It means the filter-based delete did not execute successfully against Couchbase. The original cause is logged and chained.

Source

Thrown at vector-stores/spring-ai-couchbase-store/src/main/java/org/springframework/ai/vectorstore/couchbase/CouchbaseSearchVectorStore.java:170

	public void doDelete(List<String> idList) {
		for (String id : idList) {
			this.collection.remove(id);
		}
	}

	@Override
	public void doDelete(Filter.Expression filterExpression) {
		Assert.notNull(filterExpression, "Filter expression must not be null");
		try {
			String nativeFilter = this.filterExpressionConverter.convertExpression(filterExpression);
			String sql = String.format("DELETE FROM %s WHERE %s", this.collection.name(), nativeFilter);
			this.scope.query(sql, QueryOptions.queryOptions().metrics(true));
		}
		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(org.springframework.ai.vectorstore.SearchRequest springAiRequest) {
		float[] embeddings = this.embeddingModel.embed(springAiRequest.getQuery());
		int topK = springAiRequest.getTopK();

		double similarityThreshold = springAiRequest.getSimilarityThreshold();
		Filter.Expression fe = springAiRequest.getFilterExpression();

		String nativeFilterExpression = (fe != null) ? " AND " + this.filterExpressionConverter.convertExpression(fe)
				: "";
		String statement = String.format(
				"""
						SELECT c.* FROM `%s` AS c
						WHERE SEARCH_SCORE() > %s AND SEARCH(`c`, {"query": {"match_none": {}}, "knn": [{"field": "embedding", "k": %s, "vector": %s }   ]    }, {"index": "%s.%s.%s"}   )
						%s

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Check the chained cause and logged error to see the underlying Couchbase failure
2. Verify bucket/scope/collection names and that the Query service and required indexes exist
3. Validate cluster connectivity and credentials with a simple query first
4. Print the generated N1QL filter (ElasticsearchAiSearch-style converter) and test it in the Couchbase query workbench

Example fix

// before: delete with an unindexed metadata field
delete(new Filter.Expression(ExpressionType.EQ, new MetadataKey("year"), new MetadataValue("2024")));
// after: ensure index exists first
cluster.query("CREATE PRIMARY INDEX IF NOT EXISTS ON `bucket`.`scope`.`collection`");
delete(new Filter.Expression(ExpressionType.EQ, new MetadataKey("year"), new MetadataValue("2024")));

boolean queryServiceUp = cluster.query("SELECT 1").rows().all().block() != null;

try {
    vectorStore.delete(filterExpression);
} catch (IllegalStateException e) {
    logger.error("Couchbase filter delete failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e);
    throw e;
}

When it happens

Trigger: Calling vectorStore.delete(Filter.Expression) when the Couchbase cluster/scope is unreachable, the search index does not exist, the N1QL statement is invalid, or the query fails with metrics() enabled.

Common situations: Wrong connection string/bucket/scope config, Couchbase Query service unavailable, missing primary index for the collection, network/credentials problems, or malformed filter expressions producing invalid N1QL.

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 delete documents by filter
• Not supported expression type: {expressionType}
• Failed to delete nodes by filter
• Delete operation failed

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