{"record":{"id":"74dd17ceef693fcc","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-create-index","errorCode":null,"errorMessage":"failed to create index","messagePattern":"failed to create index","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/rag/vectorstore/elasticsearch/ElasticSearchVectorStoreService.java","lineNumber":142,"sourceCode":"\t\tmetadata.put(KEY_ENABLED, Property.of(property -> property.keyword(KeywordProperty.of(k -> k))));\n\t\tmetadata.put(KEY_CHUNK_INDEX, Property.of(property -> property.keyword(KeywordProperty.of(k -> k))));\n\n\t\tproperties.put(\"metadata\",\n\t\t\t\tProperty.of(property -> property.object(ObjectProperty.of(op -> op.properties(metadata)))));\n\n\t\tCreateIndexResponse indexResponse;\n\t\ttry {\n\t\t\tindexResponse = elasticsearchClient.indices()\n\t\t\t\t.create(createIndexBuilder -> createIndexBuilder.index(indexName)\n\t\t\t\t\t.settings(indexSettings)\n\t\t\t\t\t.mappings(TypeMapping.of(mappings -> mappings.properties(properties))));\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new RuntimeException(e);\n\t\t}\n\n\t\tif (!indexResponse.acknowledged()) {\n\t\t\tthrow new RuntimeException(\"failed to create index\");\n\t\t}\n\n\t\tlog.info(\"create elasticsearch index {} successfully\", indexName);\n\t}\n\n\t/**\n\t * Deletes an existing Elasticsearch index\n\t * @param indexConfig Configuration containing the index name to delete\n\t */\n\t@Override\n\tpublic void deleteIndex(IndexConfig indexConfig) {\n\t\tString indexName = indexConfig.getName();\n\t\ttry {\n\t\t\telasticsearchClient.indices().delete(idx -> idx.index(indexName));\n\t\t}\n\t\tcatch (ElasticsearchException ex) {\n\t\t\tif (ex.response().status() == 404) {\n\t\t\t\tlog.warn(\"index {} not found\", indexName);","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/rag/vectorstore/elasticsearch/ElasticSearchVectorStoreService.java#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// pre-check cluster availability\nboolean healthy = elasticsearchClient.cluster()\n    .health(c -> c).status() == HealthStatus.Green\n    || elasticsearchClient.cluster().health(c -> c).status() == HealthStatus.Yellow;","typeGuard":null,"tryCatchPattern":"try {\n    store.createIndex(cfg);\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"failed to create index\")) {\n        // backoff and retry; inspect GET _cluster/health and ES logs\n    } else if (e.getCause() instanceof IOException io) {\n        // connection problem: verify host/port/credentials\n    }\n}","preventionTips":["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"],"tags":["elasticsearch","network","rag","retry"],"backgroundTag":"http-error-response","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}