spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

PgVectorStore.doDelete wraps the JDBC delete execution for filter-based deletion; any exception thrown by jdbcTemplate.update (SQL syntax error from the generated filter SQL, connection problems, constraint violations) is rethrown as IllegalStateException("Failed to delete documents by filter", e) with the root cause attached.

Solutions

1. Inspect the wrapped cause (e.getCause()) for the actual PostgreSQL error.
2. Verify the filter expression references valid columns and uses supported operators.
3. Check database connectivity and lock state at delete time.
4. Retry the delete if the cause is transient (connection reset).

Example fix

// before
vectorStore.delete(Filter.expressionValue("meta.author == 'unknown'")); // unknown column
// after
vectorStore.delete(Filter.expressionValue("author == 'unknown'")); // valid mapped key

Objects.requireNonNull(filter, "filter must not be null for filter-based delete");

try {
    vectorStore.delete(Filter.expressionValue(expr));
} catch (IllegalStateException e) {
    logger.error("Filter delete failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
    if (isTransient(e.getCause())) retryBackoff();
}

When it happens

Trigger: Calling vectorStore.delete(Filter.expressionValue("...")) where the generated SQL fails — invalid filter expression conversion, nonexistent column in the filter, or a database connectivity/lock issue during the UPDATE/DELETE.

Common situations: Filtering on metadata keys that map to no SQL column; SQL injection-safe but syntactically broken expressions; transient connection drops; table locked by a migration.

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

• Error while validating table schema, Table does not exist…
• Failed to delete documents by filter
• Failed to delete documents by filter
• Failed to delete documents by filter
• Failed to delete nodes by filter

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

Appendix: source

Thrown at vector-stores/spring-ai-pgvector-store/src/main/java/org/springframework/ai/vectorstore/pgvector/PgVectorStore.java:352

			@Override
			public int getBatchSize() {
				return idList.size();
			}
		});
	}

	@Override
	protected void doDelete(Filter.Expression filterExpression) {
		String filterClause = this.filterExpressionConverter.convertExpression(filterExpression);

		String sql = "DELETE FROM " + getFullyQualifiedTableName() + " WHERE " + filterClause;

		// Execute the delete
		try {
			this.jdbcTemplate.update(sql);
		}
		catch (Exception e) {
			throw new IllegalStateException("Failed to delete documents by filter", e);
		}
	}

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

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

		String jsonPathFilter = "";

		if (StringUtils.hasText(nativeFilterExpression)) {
			jsonPathFilter = " AND " + nativeFilterExpression + " ";
		}

		double distance = 1 - request.getSimilarityThreshold();

		PGvector queryEmbedding = getQueryEmbedding(request.getQuery());

View on GitHub (pinned to 98a7beda4f)