spring-projects/spring-ai · error · IllegalStateException

Failed to delete some documents:

Error message

Failed to delete some documents: 

What it means

OpenSearchVectorStore.doDelete, when deleting by filter, executes a delete_by_query; if the DeleteByQueryResponse contains failures, it throws IllegalStateException('Failed to delete some documents: ' + failures). This indicates a partial delete — some documents matching the filter could not be removed.

Solutions

1. Read the failures list in the message to identify failing shards/documents and reasons.
2. Retry the delete_by_query with conflicts=proceed semantics or during a maintenance window without concurrent writes.
3. Check cluster health and shard allocation; resolve red/yellow shards before re-running.
4. Validate the filter field mappings (metadata_ prefix) are consistent across documents.

Example fix

// before
vectorStore.delete(filterExpression); // partial failures during heavy indexing
// after
// pause ingestion, then retry
ingestionPaused = true;
vectorStore.delete(filterExpression); // conflicts eliminated
ingestionPaused = false;

Health health = client.cluster().health(h -> h); // proceed only if status != RED
if (health.status() == Status.RED) { /* defer delete */ }

try {
    vectorStore.delete(filterExpression);
} catch (IllegalStateException e) {
    // parse failures from message; retry with conflicts-proceed during quiet period
    scheduler.schedule(() -> vectorStore.delete(filterExpression), 30, TimeUnit.SECONDS);
}

When it happens

Trigger: Calling vectorStore.delete(Filter.Expression) or delete(String filterExpression) where the delete_by_query partially fails, e.g. due to document-level conflicts, version conflicts from concurrent updates, or mapping/field issues.

Common situations: Concurrent indexing while deleting by filter (version conflicts); cluster under load with timeouts on some shards; indices with conflicting mappings for metadata fields used in the filter.

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

• Delete operation failed
• Document ID management is disabled. Delete operations may…
• Failed to delete documents by filter
• Failed to delete documents by filter
• Not supported expression type:

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

Appendix: source

Thrown at vector-stores/spring-ai-opensearch-store/src/main/java/org/springframework/ai/vectorstore/opensearch/OpenSearchVectorStore.java:293

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

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

			// Create delete by query request
			DeleteByQueryRequest request = new DeleteByQueryRequest.Builder().index(this.index)
				.query(q -> q.queryString(qs -> qs.query(filterStr)))
				.build();

			DeleteByQueryResponse response = this.openSearchClient.deleteByQuery(request);
			if (logger.isDebugEnabled()) {
				logger.debug("Deleted " + response.deleted() + " documents matching filter expression");
			}

			if (!response.failures().isEmpty()) {
				throw new IllegalStateException("Failed to delete some documents: " + response.failures());
			}
		}
		catch (Exception e) {
			if (logger.isErrorEnabled()) {
				logger.error("Failed to delete documents by filter: " + e.getMessage());
			}
			throw new IllegalStateException("Failed to delete documents by filter", e);
		}
	}

	@Override
	public List<Document> doSimilaritySearch(SearchRequest searchRequest) {
		Assert.notNull(searchRequest, "The search request must not be null.");
		return similaritySearch(this.embeddingModel.embed(searchRequest.getQuery()), searchRequest.getTopK(),
				searchRequest.getSimilarityThreshold(), searchRequest.getFilterExpression());
	}

	public List<Document> similaritySearch(float[] embedding, int topK, double similarityThreshold,

View on GitHub (pinned to 98a7beda4f)