alibaba/spring-ai-alibaba · error · IllegalArgumentException

Index not found

Error message

Index not found

What it means

ElasticsearchVectorStore.doAdd refuses to write documents unless the target index already exists in Elasticsearch. The index must be pre-created or the store must have been built with initializeSchema=true, which creates the index during initialization.

Solutions

1. Set initializeSchema(true) when building the ElasticsearchVectorStore so the index is created automatically.
2. Pre-create the index with an appropriate mapping before adding documents.
3. Verify the index name in options matches an existing index (GET /_cat/indices).
4. Check Elasticsearch connectivity/permissions — indexExists() may report false if the client cannot reach the cluster.

Example fix

// before
ElasticsearchVectorStore store = ElasticsearchVectorStore.builder(elasticsearchClient, embeddingModel)
    .options(ElasticsearchVectorStoreOptions.options().indexName("docs"))
    .build();
// after
ElasticsearchVectorStore store = ElasticsearchVectorStore.builder(elasticsearchClient, embeddingModel)
    .options(ElasticsearchVectorStoreOptions.options().indexName("docs"))
    .initializeSchema(true)
    .build();

// Java: check index presence before adding
boolean request = new ExistsRequest.Builder().index(indexName).build();
boolean exists = elasticsearchClient.cluster().state(...).toString().contains(indexName); // or client.indices().exists(r -> r.index(indexName)).value();
if (!exists) { elasticsearchClient.indices().create(c -> c.index(indexName)); }

try { vectorStore.add(docs); } catch (IllegalArgumentException e) {
    if ("Index not found".equals(e.getMessage())) { elasticsearchClient.indices().create(c -> c.index(indexName)); vectorStore.add(docs); }
    else throw e;
}

When it happens

Trigger: Calling VectorStore.add(documents) (which invokes doAdd) when the configured index (options.getIndexName()) does not exist because initializeSchema was false and nobody created the index.

Common situations: Fresh Elasticsearch cluster or changed index name in options; initialize-schema property left at default false in Spring Boot config; index deleted by ILM/retention policies or manual cleanup.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Delete operation failed
• Failed to delete documents by filter
• hybrid alpha should be between 0 ~ 1.
• Unsupported search type:
• Elastic search index name must be provided

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/58e2ad4e18d72a3e. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java:187

		Assert.notNull(builder.restClient, "RestClient must not be null");

		this.initializeSchema = builder.initializeSchema;
		this.options = builder.options;
		this.filterExpressionConverter = builder.filterExpressionConverter;

		String version = Version.VERSION == null ? "Unknown" : Version.VERSION.toString();
		this.elasticsearchClient = new ElasticsearchClient(new RestClientTransport(builder.restClient,
				new JacksonJsonpMapper(
						new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false))))
			.withTransportOptions(t -> t.addHeader("user-agent", "spring-ai elastic-java/" + version));
	}

	@Override
	public void doAdd(List<Document> documents) {
		// For the index to be present, either it must be pre-created or set the
		// initializeSchema to true.
		if (!indexExists()) {
			throw new IllegalArgumentException("Index not found");
		}
		BulkRequest.Builder bulkRequestBuilder = new BulkRequest.Builder();

		List<float[]> embeddings = this.embeddingModel.embed(documents,  EmbeddingOptions.builder().build(),
				this.batchingStrategy);

		for (Document document : documents) {
			ElasticSearchDocument doc = new ElasticSearchDocument(document.getId(), document.getText(),
					document.getMetadata(), embeddings.get(documents.indexOf(document)));
			bulkRequestBuilder.operations(
					op -> op.index(idx -> idx.index(this.options.getIndexName()).id(document.getId()).document(doc)));
		}
		BulkResponse bulkRequest = bulkRequest(bulkRequestBuilder.build());
		if (bulkRequest.errors()) {
			List<BulkResponseItem> bulkResponseItems = bulkRequest.items();
			for (BulkResponseItem bulkResponseItem : bulkResponseItems) {
				if (bulkResponseItem.error() != null) {
					throw new IllegalStateException(bulkResponseItem.error().reason());

View on GitHub (pinned to f82da0b50f)