spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

When deleting documents by a FilterExpression, RedisVectorStore.doDelete() wraps the whole FT.SEARCH-and-delete operation in a try/catch and rethrows any Exception as IllegalStateException 'Failed to delete documents by filter' with the original cause attached. It indicates the filter-based delete failed at some stage: query execution, result parsing, or the deletion commands themselves.

Source

Thrown at vector-stores/spring-ai-redis-store/src/main/java/org/springframework/ai/vectorstore/redis/RedisVectorStore.java:453

					if (errResponse.isPresent()) {
						if (logger.isErrorEnabled()) {
							logger.error("Could not delete document: " + errResponse.get());
						}
						throw new IllegalStateException("Failed to delete some documents");
					}
				}

				deletedCount += docs.size();
			}

			if (logger.isDebugEnabled()) {
				logger.debug("Deleted " + deletedCount + " documents matching filter expression");
			}
		}
		catch (Exception e) {
			logger.error("Failed to delete documents by filter", e);
			throw new IllegalStateException("Failed to delete documents by filter", e);
		}
	}

	@Override
	public List<Document> doSimilaritySearch(SearchRequest request) {

		Assert.isTrue(request.getTopK() > 0, "The number of documents to be returned must be greater than zero");
		Assert.isTrue(request.getSimilarityThreshold() >= 0 && request.getSimilarityThreshold() <= 1,
				"The similarity score is bounded between 0 and 1; least to most similar respectively.");

		// For the IP metric we need to adjust the threshold
		final float effectiveThreshold;
		if (this.distanceMetric == DistanceMetric.IP) {
			// For IP metric, temporarily disable threshold filtering
			effectiveThreshold = 0.0f;
		}
		else {
			effectiveThreshold = (float) request.getSimilarityThreshold();

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Inspect the wrapped cause exception (getCause()) for the underlying Redis error
2. Confirm the index exists and the filter references indexed fields with correct names/types
3. Validate the filter expression against the metadata schema before deleting
4. Check Redis connectivity and timeouts; retry once connectivity is restored

// Validate the filter references indexed fields
Map<String,Object> info = jedisClient.ftInfo(indexName); // confirm field names/types before delete-by-filter

try { store.delete(filterExpr); } catch (IllegalStateException e) { log.error("Filter delete failed", e.getCause()); }

When it happens

Trigger: Calling vectorStore.delete(filterExpression) with a malformed filter, an index that does not exist, a field name not present in the index schema, or a Redis connection that breaks mid-operation.

Common situations: Filter referencing a metadata field not indexed (wrong name or type); Redis index dropped/recreated while deleting; network/timeout issues to Redis; query syntax errors produced by an unsupported filter expression.

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
• Failed to delete some documents
• Failed to execute count query
• 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/70c9c42ce5bd39ff. Report an issue: GitHub.