{"record":{"id":"bb49bcdc5a5a5063","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-delete-documents-by-filter","errorCode":null,"errorMessage":"Failed to delete documents by filter","messagePattern":"Failed to delete documents by filter","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java","lineNumber":240,"sourceCode":"\t\tif (bulkRequest(bulkRequestBuilder.build()).errors()) {\n\t\t\tthrow new IllegalStateException(\"Delete operation failed\");\n\t\t}\n\t}\n\n\t@Override\n\tpublic void doDelete(Filter.Expression filterExpression) {\n\t\t// For the index to be present, either it must be pre-created or set the\n\t\t// initializeSchema to true.\n\t\tif (!indexExists()) {\n\t\t\tthrow new IllegalArgumentException(\"Index not found\");\n\t\t}\n\n\t\ttry {\n\t\t\tthis.elasticsearchClient.deleteByQuery(d -> d.index(this.options.getIndexName())\n\t\t\t\t.query(q -> q.queryString(qs -> qs.query(getElasticsearchQueryString(filterExpression)))));\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new IllegalStateException(\"Failed to delete documents by filter\", e);\n\t\t}\n\t}\n\n\tprivate BulkResponse bulkRequest(BulkRequest bulkRequest) {\n\t\ttry {\n\t\t\treturn this.elasticsearchClient.bulk(bulkRequest);\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new RuntimeException(e);\n\t\t}\n\t}\n\n\t@Override\n\tpublic List<Document> doSimilaritySearch(SearchRequest searchRequest) {\n\t\tAssert.notNull(searchRequest, \"The search request must not be null.\");\n\n\t\treturn switch (searchRequest.getSearchType()) {\n\t\t\tcase SEMANTIC -> searchBySemantic(searchRequest);","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java#L222-L258","documentation":"If the delete-by-query request executed in doDelete(Filter.Expression) throws for any reason, it is wrapped and rethrown as IllegalStateException(\"Failed to delete documents by filter\", e) with the original exception as the cause. The index exists, but the query delete itself failed.","triggerScenarios":"Calling VectorStore.delete(Filter.Expression) when the deleteByQuery call fails: malformed/unconvertible filter expression producing an invalid query_string, query parse errors, cluster/shard unavailability, timeouts, or permission errors.","commonSituations":"Filter expressions that translate to invalid Elasticsearch query_string syntax; red cluster status; delete-by-query hitting the 429 or 503 due to load; missing field mappings making the query invalid.","solutions":["Inspect the wrapped cause (e.getCause()) for the concrete Elasticsearch error (parse_error, 429, 503, etc.).","Validate that the Filter.Expression converts to a valid query (log getElasticsearchQueryString(filterExpression)).","Check cluster health and retry if the failure was due to shard unavailability or throttling.","Simplify or correct the filter expression; verify field names exist in the index mapping."],"exampleFix":"// before\ncatch (Exception e) { throw new IllegalStateException(\"Failed to delete documents by filter\", e); }\n// after\ncatch (Exception e) {\n    logger.error(\"deleteByQuery failed, query={}\", getElasticsearchQueryString(filterExpression), e);\n    throw new IllegalStateException(\"Failed to delete documents by filter: \" + e.getMessage(), e);\n}","handlingStrategy":"try-catch","validationCode":"// Java: sanity-check the converted query before executing\nString qs = new ElasticsearchAiSearchFilterExpressionConverter().convertExpression(filterExpression);\nif (qs == null || qs.isBlank()) throw new IllegalArgumentException(\"filter converts to empty query\");","typeGuard":null,"tryCatchPattern":"try { vectorStore.delete(filterExpression); } catch (IllegalStateException e) {\n    Throwable root = e.getCause();\n    log.error(\"delete-by-query failed: {}\", root == null ? \"unknown\" : root.getMessage(), root);\n    if (isTransient(root)) retryAfterBackoff(); else throw e;\n}","preventionTips":["Log the Elasticsearch query string generated from the filter for validation.","Test filter expressions against a staging index mapping.","Handle 429/503 with backoff retries; they are common under load.","Verify field names in Filter.Expression match index mappings."],"tags":["elasticsearch","vector-store","delete-by-query"],"backgroundTag":"database-query-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}