spring-projects/spring-ai · error · IllegalStateException

Delete operation failed

Error message

Delete operation failed

What it means

OpenSearchVectorStore.doDelete builds a BulkRequest of delete operations; if the returned BulkResponse reports errors=true, it throws IllegalStateException('Delete operation failed'). The individual per-item failure details are in the BulkResponse, which this throw does not attach, so you must inspect the bulk response or logs for specifics.

Source

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

					.operations(op -> op.index(idx -> idx.index(this.index).document(openSearchDocument)));
			}
		}
		bulkRequest(bulkRequestBuilder.build());
	}

	@Override
	public void doDelete(List<String> idList) {
		if (!this.manageDocumentIds) {
			logger.warn("Document ID management is disabled. Delete operations may not work as expected "
					+ "since document IDs are auto-generated by OpenSearch. Consider using filter-based deletion instead.");
		}

		BulkRequest.Builder bulkRequestBuilder = new BulkRequest.Builder();
		for (String id : idList) {
			bulkRequestBuilder.operations(op -> op.delete(idx -> idx.index(this.index).id(id)));
		}
		if (bulkRequest(bulkRequestBuilder.build()).errors()) {
			throw new IllegalStateException("Delete operation failed");
		}
	}

	private BulkResponse bulkRequest(BulkRequest bulkRequest) {
		try {
			return this.openSearchClient.bulk(bulkRequest);
		}
		catch (IOException e) {
			throw new RuntimeException(e);
		}
	}

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

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

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Enable debug logging or capture the BulkResponse items to see which ids failed and why.
2. Check the OpenSearch cluster health and disk watermarks (read-only index blocks cause delete failures).
3. Verify the ids exist in the target index before deleting, or ignore 404-style item failures.
4. Retry the delete for the failed subset of ids.

Example fix

// before
vectorStore.delete(ids); // opaque failure
// after
try {
    vectorStore.delete(ids);
} catch (IllegalStateException e) {
    // inspect cluster: GET /_cluster/health and per-item bulk errors
    ids.forEach(id -> indexOps.exists(id)); // confirm which docs are missing
}

// ensure cluster is writable before bulk delete
boolean writable = client.cluster().health().status() == Status.GREEN
    || client.cluster().health().status() == Status.YELLOW;

try {
    vectorStore.delete(ids);
} catch (IllegalStateException e) {
    // inspect cluster/bulk item errors, then retry the failed subset
    retryDelete(ids);
}

When it happens

Trigger: Calling vectorStore.delete(List<String> ids) where at least one bulk delete item fails on the OpenSearch cluster (e.g. document missing under strict mapping, index issues, cluster connectivity problems that still yield a response).

Common situations: Deleting documents by ids that were already removed or never indexed while the index uses external versioning/strict settings; OpenSearch cluster returning partial failures; index read-only due to disk watermark exceeded.

Related errors

• Delete operation failed
• Failed to delete documents by filter
• Failed to delete documents by filter
• Failed to delete documents by filter
• Failed to delete documents by filter

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