alibaba/spring-ai-alibaba · error · RuntimeException
failed to create index
Error message
failed to create index
What it means
After issuing the Elasticsearch create-index request, the service checks indexResponse.acknowledged(); if the cluster did not acknowledge index creation it wraps the failure in RuntimeException("failed to create index"). A second variant rethrows IOException from the request itself.
Source
Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/rag/vectorstore/elasticsearch/ElasticSearchVectorStoreService.java:142
metadata.put(KEY_ENABLED, Property.of(property -> property.keyword(KeywordProperty.of(k -> k))));
metadata.put(KEY_CHUNK_INDEX, Property.of(property -> property.keyword(KeywordProperty.of(k -> k))));
properties.put("metadata",
Property.of(property -> property.object(ObjectProperty.of(op -> op.properties(metadata)))));
CreateIndexResponse indexResponse;
try {
indexResponse = elasticsearchClient.indices()
.create(createIndexBuilder -> createIndexBuilder.index(indexName)
.settings(indexSettings)
.mappings(TypeMapping.of(mappings -> mappings.properties(properties))));
}
catch (IOException e) {
throw new RuntimeException(e);
}
if (!indexResponse.acknowledged()) {
throw new RuntimeException("failed to create index");
}
log.info("create elasticsearch index {} successfully", indexName);
}
/**
* Deletes an existing Elasticsearch index
* @param indexConfig Configuration containing the index name to delete
*/
@Override
public void deleteIndex(IndexConfig indexConfig) {
String indexName = indexConfig.getName();
try {
elasticsearchClient.indices().delete(idx -> idx.index(indexName));
}
catch (ElasticsearchException ex) {
if (ex.response().status() == 404) {
log.warn("index {} not found", indexName);View on GitHub (pinned to f82da0b50f)
Solutions
- Check Elasticsearch cluster health and logs (GET _cluster/health) — resolve red status or disk watermark blocks (free space or raise flood_stage limit)
- Verify connection settings (host, port, credentials) and retry index creation after the cluster recovers
- Inspect the actual ES error by calling the create-index API manually with the same index name/settings; fix invalid mappings or settings returned there
Defensive patterns
Strategy: retry
Validate before calling
// pre-check cluster availability
boolean healthy = elasticsearchClient.cluster()
.health(c -> c).status() == HealthStatus.Green
|| elasticsearchClient.cluster().health(c -> c).status() == HealthStatus.Yellow; Try / catch
try {
store.createIndex(cfg);
} catch (RuntimeException e) {
if (e.getMessage().contains("failed to create index")) {
// backoff and retry; inspect GET _cluster/health and ES logs
} else if (e.getCause() instanceof IOException io) {
// connection problem: verify host/port/credentials
}
} Prevention
- Monitor cluster health and disk watermarks
- Verify connectivity before provisioning
- Make index creation idempotent (exists check) and retry with backoff
- Check ES logs for real cause when acknowledged=false
When it happens
Trigger: Elasticsearch returns acknowledged=false — typically because the request timed out while the cluster was busy/relocating shards, the cluster health is red, or disk watermark thresholds are exceeded. The IOException variant fires on connection failure to the cluster.
Common situations: Elasticsearch cluster at red health or under load; low disk space triggering flood-stage watermark (index blocked); wrong host/port so the client call fails; index name invalid per ES naming rules causing a server-side error.
Understand the failure class
Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.
Related errors
AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09).
Data as JSON: /api/errors/74dd17ceef693fcc.
Report an issue: GitHub.