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

Inspect the cause exception in the IllegalStateException to identify the underlying Milvus client failure.

spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

MilvusVectorStore.doDelete wraps any exception raised while deleting documents matching a Filter expression into an IllegalStateException. The Milvus client delete call or the filter-expression conversion failed, so the delete could not be completed. The original exception is attached as the cause and logged.

Source

Thrown at vector-stores/spring-ai-milvus-store/src/main/java/org/springframework/ai/vectorstore/milvus/MilvusVectorStore.java:354

			if (StringUtils.hasText(this.partitionName)) {
				deleteParamBuilder.withPartitionName(this.partitionName);
			}
			R<MutationResult> status = this.milvusClient.delete(deleteParamBuilder.build());

			if (status.getStatus() != Status.Success.getCode()) {
				throw new IllegalStateException("Failed to delete documents by filter: " + status.getMessage());
			}

			long deleteCount = status.getData().getDeleteCnt();
			if (logger.isDebugEnabled()) {
				logger.debug("Deleted " + deleteCount + " documents matching filter expression");
			}
		}
		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 nativeFilterExpressions = "";
		String searchParamsJson = null;
		if (request instanceof MilvusSearchRequest milvusReq) {
			nativeFilterExpressions = StringUtils.hasText(milvusReq.getNativeExpression())
					? milvusReq.getNativeExpression() : getConvertedFilterExpression(request);

			searchParamsJson = StringUtils.hasText(milvusReq.getSearchParamsJson()) ? milvusReq.getSearchParamsJson()
					: null;
		}
		else {
			nativeFilterExpressions = getConvertedFilterExpression(request);
		}

View on GitHub (pinned to 98a7beda4f)

Solutions

Inspect the cause exception in the IllegalStateException to identify the underlying Milvus client failure.
Verify the Milvus server is running and reachable (host/port/credentials in MilvusServiceClient builder).
Ensure the collection is loaded (LoadCollection) before deleting.
Validate the filter expression syntax and that field names match the store's configured content/metadata field names.
Retry the delete once connectivity is restored.

Example fix

// before
vectorStore.delete("country == 'Bulagaria'");
// after
vectorStore.delete("country == 'Bulgaria'"); // fix typo in filter expression

Defensive patterns

Strategy: try-catch

Validate before calling

// before deleting, check server reachability and collection existence
if (!milvusClient.hasCollection(HasCollectionParam.newBuilder()
        .withCollectionName(collectionName).build()).getData(Boolean.FALSE)) {
    throw new IllegalStateException("Collection " + collectionName + " does not exist");
}

Try / catch

try {
    vectorStore.delete("country == 'Bulgaria'");
} catch (IllegalStateException e) {
    logger.error("Milvus delete failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
    // inspect e.getCause() for the Milvus RPC status before retrying
}

Prevention

Test filter expressions against a small dataset before production deletes.
Keep Milvus server health checks in place before batch delete operations.
Ensure metadata field names in filters match the store's metadataFieldName configuration.

When it happens

Trigger: Calling vectorStore.delete(String filterExpression) or delete(Filter...) when the Milvus client deleteByFilter RPC fails (connection loss, collection not loaded, malformed filter expression, embedding/metadata field name mismatch).

Common situations: Milvus server unreachable or restarted; collection not loaded into memory; filter expression referencing a metadata field that is not the configured metadataFieldName; invalid filter syntax produced by the expression converter.

Related errors

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