spring-projects/spring-ai · warning

Document ID management is disabled. Delete operations may…

Error message

Document ID management is disabled. Delete operations may not work as expected since document IDs are auto-generated by OpenSearch. Consider using filter-based deletion instead.

What it means

OpenSearchVectorStore.doDelete warns when manageDocumentIds is disabled. In that mode document ids are auto-generated by OpenSearch at index time, so the store cannot map Spring AI Document ids to OpenSearch _id values and delete-by-id may remove nothing or the wrong documents. Filter-based deletion is the supported alternative.

Solutions

1. Enable id management: OpenSearchVectorStore.builder(embeddingModel, openSearchClient).withManageDocumentIds(true).build()
2. Use delete(FilterExpression) (filter-based deletion) instead of delete-by-id when id management is off
3. Re-index existing documents through the store with id management enabled so ids are recorded
4. Suppress/ignore the warning if you only ever delete via filters

Example fix

// before
OpenSearchVectorStore store = OpenSearchVectorStore.builder(embeddingModel, client).build();

// after
OpenSearchVectorStore store = OpenSearchVectorStore.builder(embeddingModel, client)
    .withManageDocumentIds(true)
    .build();

// ensure id management is on before relying on delete-by-id
if (!isManageDocumentIdsEnabled(store)) {
    throw new IllegalStateException("Use delete(FilterExpression) or enable withManageDocumentIds(true)");
}

When it happens

Trigger: Calling vectorStore.delete(List.of(id)) on a store built without document id management enabled (OpenSearchVectorStore.builder(...).withManageDocumentIds(true) not set).

Common situations: Default builder configuration where add() documents were stored with OpenSearch-generated ids; upgrading from a setup that never managed ids; mixed writes from other tools that bypass the store's id mapping.

Related errors

• Delete operation failed
• Failed to delete documents by filter
• argumentType is required
• At least one client Id must be specified
• At least one client Id must be specified

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

Appendix: source

Thrown at vector-stores/spring-ai-opensearch-store/src/main/java/org/springframework/ai/vectorstore/opensearch/OpenSearchVectorStore.java:253

					Objects.requireNonNullElse(document.getText(), ""), document.getMetadata(), embedding.get(i));

			// Conditionally set document ID based on manageDocumentIds flag
			if (this.manageDocumentIds) {
				bulkRequestBuilder.operations(op -> op
					.index(idx -> idx.index(this.index).id(openSearchDocument.id()).document(openSearchDocument)));
			}
			else {
				bulkRequestBuilder
					.operations(op -> op.index(idx -> idx.index(this.index).document(openSearchDocument)));
			}
		}
		bulkRequest(bulkRequestBuilder.build());
	}

	@Override
	public void doDelete(List<String> idList) {
		if (!this.manageDocumentIds) {
			logger.warn("Document ID management is disabled. Delete operations may not work as expected "
					+ "since document IDs are auto-generated by OpenSearch. Consider using filter-based deletion instead.");
		}

		BulkRequest.Builder bulkRequestBuilder = new BulkRequest.Builder();
		for (String id : idList) {
			bulkRequestBuilder.operations(op -> op.delete(idx -> idx.index(this.index).id(id)));
		}
		if (bulkRequest(bulkRequestBuilder.build()).errors()) {
			throw new IllegalStateException("Delete operation failed");
		}
	}

	private BulkResponse bulkRequest(BulkRequest bulkRequest) {
		try {
			return this.openSearchClient.bulk(bulkRequest);
		}
		catch (IOException e) {
			throw new RuntimeException(e);

View on GitHub (pinned to 98a7beda4f)