spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

TypesenseVectorStore.doDelete wraps any exception thrown while deleting documents matching a filter expression (search + delete via the Typesense client) into an IllegalStateException with this message, after logging the original error. It indicates the delete-by-filter operation failed at the client/HTTP level, not that the filter was invalid.

Source

Thrown at vector-stores/spring-ai-typesense-store/src/main/java/org/springframework/ai/vectorstore/typesense/TypesenseVectorStore.java:222

			String filterStr = this.filterExpressionConverter.convertExpression(filterExpression);
			DeleteDocumentsParameters deleteDocumentsParameters = new DeleteDocumentsParameters();
			deleteDocumentsParameters.filterBy(filterStr);

			Map<String, Object> response = this.client.collections(this.collectionName)
				.documents()
				.delete(deleteDocumentsParameters);

			int deletedDocs = (Integer) response.getOrDefault("num_deleted", 0);
			if (deletedDocs == 0) {
				logger.warn("No documents were deleted matching filter expression");
			}
			else if (logger.isDebugEnabled()) {
				logger.debug("Deleted " + deletedDocs + " 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.notNull(request.getQuery(), "Query string must not be null");

		String nativeFilterExpressions = (request.getFilterExpression() != null)
				? this.filterExpressionConverter.convertExpression(request.getFilterExpression()) : "";

		if (logger.isInfoEnabled()) {
			logger.info("Filter expression: " + nativeFilterExpressions);
		}

		float[] embedding = this.embeddingModel.embed(request.getQuery());

		MultiSearchCollectionParameters multiSearchCollectionParameters = new MultiSearchCollectionParameters();
		multiSearchCollectionParameters.collection(this.collectionName);

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Inspect the logged cause (logger.error prints the root exception) and fix the underlying Typesense connectivity/permission/collection issue.
2. Verify the Typesense client configuration (host, port, API key) and that the target collection exists.
3. Retry the delete; if transient network errors are common, wrap with retry/backoff.
4. Convert the filter to filter_by syntax manually and test it with curl against the collection's documents endpoint to find syntax problems.

Example fix

// before
vectorStore.delete(new Filter.Expression(GT, new Key("year"), new Value(2000))); // fails silently root-caused
// after: ensure collection & connectivity
CollectionsOperations coll = typesenseClient.collections("my_collection");
coll.retrieve(); // verify reachable before delete
vectorStore.delete(filterExpr);

// pre-check connectivity
typesenseClient.collections(collectionName).retrieve();

try { vectorStore.delete(filterExpr); } catch (IllegalStateException e) { logger.error("Delete-by-filter failed; cause:", e.getCause()); /* inspect Typesense host/port/key/collection */ }

When it happens

Trigger: Calling vectorStore.delete(filterExpression) when the Typesense collection is unreachable, the collection doesn't exist, the filter converts to invalid filter_by syntax, or the client throws any Exception during the delete flow.

Common situations: Typesense server down or wrong host/port; API key lacking delete permissions; collection deleted or renamed while the store is in use; a filter that serializes to filter_by syntax Typesense rejects.

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 all documents
• Failed to delete documents by filter
• Failed to delete documents by filter
• Failed to delete documents by filter
• Delete operation failed

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