spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

OpenSearchVectorStore.doDelete catches any exception thrown while performing the filter-based delete (building the query, executing delete_by_query) and rethrows it as IllegalStateException('Failed to delete documents by filter') with the original as cause. It is a wrapper ensuring a uniform exception type for filter deletes.

Source

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

			// 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,
			Filter.@Nullable Expression filterExpression) {
		return similaritySearch(
				this.useApproximateKnn ? buildApproximateQuery(embedding, topK, similarityThreshold, filterExpression)
						: buildExactQuery(embedding, topK, similarityThreshold, filterExpression));
	}

	private org.opensearch.client.opensearch.core.SearchRequest buildApproximateQuery(float[] embedding, int topK,

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Inspect the cause exception and the logged 'Failed to delete documents by filter' message for the root error.
2. Verify OpenSearch connection settings (url, credentials) and cluster availability.
3. Simplify/validate the filter expression and confirm the metadata field names exist in the index mapping.
4. Retry after transient network errors; wrap calls in retry logic with backoff.

Example fix

// before
vectorStore.delete("counrty == 'IN'"); // typo yields broken query DSL
// after
vectorStore.delete("country == 'IN'"); // valid field, delete succeeds

// validate connectivity and index existence first
boolean exists = client.indices().exists(i -> i.index(index)).value();
boolean reachable = pingClient();

try {
    vectorStore.delete(filterExpression);
} catch (IllegalStateException e) {
    Throwable cause = e.getCause();
    logger.error("Filter delete failed: {}", cause == null ? e.getMessage() : cause.getMessage(), cause);
}

When it happens

Trigger: Calling vectorStore.delete(Filter.Expression) or delete(String) when the OpenSearch client throws — connectivity loss, malformed filter converting to invalid query DSL, index missing, or authentication errors.

Common situations: OpenSearch endpoint down or wrong host/port in config; invalid filter syntax that the converter renders into broken query DSL; security plugin rejecting the request; index deleted between existence check and query.

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
• 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/8de18d5888d73cdb. Report an issue: GitHub.