spring-projects/spring-ai · error · IllegalStateException

Failed to delete documents by filter

Error message

Failed to delete documents by filter

What it means

OracleVectorStore.doDelete catches any exception during delete-by-id or delete-by-filter (JDBC execution of DELETE statements) and rethrows as IllegalStateException('Failed to delete documents by filter') with the cause attached. The root reason is in the chained cause and the error log.

Source

Thrown at vector-stores/spring-ai-oracle-store/src/main/java/org/springframework/ai/vectorstore/oracle/OracleVectorStore.java:331

		try {
			String filterClause = this.filterExpressionConverter.convertExpression(filterExpression);
			String sql = String.format("DELETE FROM %s WHERE %s", this.tableName, filterClause);

			if (logger.isDebugEnabled()) {
				logger.debug("Executing delete with filter: " + sql);
			}

			int deletedCount = this.jdbcTemplate.update(sql);
			if (logger.isDebugEnabled()) {
				logger.debug("Deleted " + deletedCount + " documents matching filter expression");
			}
		}
		catch (Exception e) {
			if (logger.isErrorEnabled()) {
				logger.error("Failed to delete documents by filter: " + e.getMessage(), e);
			}
			throw new IllegalStateException("Failed to delete documents by filter", e);
		}
	}

	@Override
	public List<Document> doSimilaritySearch(SearchRequest request) {
		try {
			// From the provided query, generate a vector using the embedding model
			final VECTOR embeddingVector = toVECTOR(this.embeddingModel.embed(request.getQuery()));

			if (logger.isDebugEnabled()) {
				this.jdbcTemplate.batchUpdate("insert into debug(embedding) values(?)",
						new BatchPreparedStatementSetter() {

							@Override
							public void setValues(PreparedStatement ps, int i) throws SQLException {
								org.springframework.jdbc.core.StatementCreatorUtils.setParameterValue(ps, 1,
										OracleType.VECTOR.getVendorTypeNumber(), embeddingVector);
							}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Read the chained cause (getCause()) for the exact SQLException and error code (e.g. ORA-00942 table not found, ORA-00054 locked).
2. Verify the Oracle connection config and that the vector store table exists with expected schema.
3. Check user privileges (DELETE on the table) and resolve row-lock contention.
4. Validate the filter expression maps to real metadata columns.

Example fix

// before
// ORA-00942 because table was created by another schema user
vectorStore.delete(ids);
// after
// run as correct user or grant: GRANT DELETE ON vector_store TO ai_user;
vectorStore.delete(ids);

// check table access before delete
jdbcTemplate.queryForObject("SELECT COUNT(*) FROM user_tab_privs WHERE table_name = 'SPRING_AI_VECTORS' AND privilege = 'DELETE'", Integer.class);

try {
    oracleVectorStore.delete(idsOrFilter);
} catch (IllegalStateException e) {
    Throwable cause = e.getCause();
    if (cause instanceof SQLException sqlEx) {
        logger.error("Oracle delete failed: ORA-{}", sqlEx.getErrorCode(), sqlEx);
    }
}

When it happens

Trigger: Calling vectorStore.delete(ids) or delete(filterExpression) when the JDBC delete fails — connection errors, SQL syntax from filter conversion, table/column missing, constraint violations, or lock timeouts.

Common situations: Oracle DB credentials/network misconfigured; filter rendered against nonexistent metadata columns; row locks held by other transactions; insufficient user privileges to delete from the vector store table.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

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

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