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 issues a delete RPC with a filter expression builder. If the returned R<MutationResult> status code is not Status.Success, it throws an IllegalStateException including the SDK's status message. Unlike the insert path, this surfaces the Milvus error message in the exception text.

Source

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

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

		try {
			String nativeFilterExpression = this.filterExpressionConverter.convertExpression(filterExpression);

			DeleteParam.Builder deleteParamBuilder = DeleteParam.newBuilder()
				.withDatabaseName(this.databaseName)
				.withCollectionName(this.collectionName)
				.withExpr(nativeFilterExpression);
			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 = "";

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Read status.getMessage() embedded in the exception for the exact Milvus error.
2. Verify the filter expression uses valid Milvus boolean syntax and only existing schema fields.
3. Load the collection (collection.load()) if it is not loaded into memory.
4. Confirm the partitionName exists or remove it from configuration.
5. Check Milvus server connectivity and SDK/server version compatibility.

Example fix

// before
vectorStore.delete(new FilterExpressionBuilder().not(
    new FilterExpressionBuilder().eq("type", "tmp")).build()); // unsupported in Milvus
// after
vectorStore.delete(new FilterExpressionBuilder().ne("type", "tmp").build());

// Validate fields referenced by the delete filter exist in the schema, and
// confirm the configured partition exists before calling delete.

try {
    vectorStore.delete(idsOrFilter);
} catch (IllegalStateException e) {
    // message contains Milvus status.getMessage(); parse and branch:
    // - collection not loaded -> load then retry
    // - invalid expression -> rewrite filter
    // - transient -> retry with backoff
}

When it happens

Trigger: Calling vectorStore.delete(List<String> ids) or delete(FilterExpression) when Milvus rejects the delete: invalid filter expression syntax for Milvus boolean grammar, collection not loaded, nonexistent partition, expression referencing fields not in the schema, or connectivity failures.

Common situations: Filter expressions using operators Milvus doesn't accept (e.g. unsupported NOT), deleting by metadata field that was never stored, partitionName configured but partition missing, collection in unloaded state after server restart.

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
• Not supported expression type: {expressionType}
• Failed to delete documents by filter
• Deleted only ${deleteCount} entries from requested ${idList.
• Unsupported operand type:

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