What causes "Failed to delete documents by filter" in spring-projects/spring-ai?

Inspect the cause attached to the IllegalStateException; fix the underlying CQL/driver error it reports.

spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

CassandraVectorStore.doDelete wraps the whole filter-based document deletion (building the CQL DELETE, executing it) in a try/catch and rethrows any failure as IllegalStateException with this message, preserving the cause. It means the delete statement or session interaction failed, not that zero documents matched.

Source

Thrown at vector-stores/spring-ai-cassandra-store/src/main/java/org/springframework/ai/vectorstore/cassandra/CassandraVectorStore.java:348

				.filterExpression(filterExpression)
				.topK(1000) // large enough to get all matches
				.similarityThresholdAll()
				.build();

			List<Document> matchingDocs = similaritySearch(searchRequest);

			if (!matchingDocs.isEmpty()) {
				// Then delete those documents by ID
				List<String> idsToDelete = matchingDocs.stream().map(Document::getId).toList();
				delete(idsToDelete);
				if (logger.isDebugEnabled()) {
					logger.debug("Deleted " + idsToDelete.size() + " documents matching filter expression");
				}
			}
		}
		catch (Exception e) {
			logger.error("Failed to delete documents by filter", e);
			throw new IllegalStateException("Failed to delete documents by filter", e);
		}
	}

	@Override
	public List<Document> doSimilaritySearch(SearchRequest request) {
		Preconditions.checkArgument(request.getTopK() <= 1000);
		var embedding = toFloatArray(this.embeddingModel.embed(request.getQuery()));
		CqlVector<Float> cqlVector = CqlVector.newInstance(embedding);
		String cql = createSimilaritySearchCql(request, cqlVector, request.getTopK());

		List<Document> documents = new ArrayList<>();
		ResultSet result = this.session
			.execute(SimpleStatement.newInstance(cql).setExecutionProfileName(DRIVER_PROFILE_SEARCH));

		for (Row row : result) {
			float score = row.getFloat(0);
			if (score < request.getSimilarityThreshold()) {
				break;

View on GitHub (pinned to 98a7beda4f)

Solutions

Inspect the cause attached to the IllegalStateException; fix the underlying CQL/driver error it reports.
Verify the schema config (keyspace, table, index) matches the actual Cassandra schema and that the session is connected.
Check Cassandra role permissions: the configured user needs MODIFY on the target table.
Confirm the filter expression renders valid CQL by simplifying it to a basic equality filter and retrying.

Example fix

// before: filter referencing a non-existent metadata column
vectorStore.delete(new FilterExpressionBuilder().eq("meta.tag", "x").build());
// after: ensure the column exists in the table / schema metadata columns
vectorStore.delete(new FilterExpressionBuilder().eq("metadata_tag", "x").build());

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check: cluster reachable and role can modify
CqlSession s = ...;
Row r = s.execute("SELECT count(*) FROM system_schema.tables WHERE keyspace_name=? AND table_name=?", ks, tbl).one();
if (r == null || r.getLong(0) == 0) throw new IllegalStateException("Table missing before delete");

Type guard

null

Try / catch

try {
  vectorStore.delete(filterExpression);
} catch (IllegalStateException e) {
  Throwable root = ExceptionUtils.getRootCause(e);
  logger.error("Cassandra delete failed: {}", root.getMessage(), root);
}

Prevention

Always log/read the wrapped cause — this exception is only a wrapper.
Validate keyspace/table config against system_schema at startup.
Grant MODIFY on the target table to the store's Cassandra role.
Test filter expressions against a local Cassandra before production deletes.

When it happens

Trigger: Executing vectorStore.delete(filterExpression) where the CQL statement fails: invalid filter-to-CQL conversion output, table/index mismatch, session/connection error, or permission denied on the keyspace/table.

Common situations: Wrong keyspace or table configured in the schema; the driver session is closed or unreachable; insufficient CQL permissions (no MODIFY on the table); a filter expression that compiled to invalid CQL.

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

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