适用版本： 6.8-8.9
1. 错误异常的基本描述 #
Failed to list store metadata for shard [request.shardId] 出现在节点本地执行 listStoreMetadata(request) 失败时。这里不是查询链路，也不是仓库列举，而是某个节点在响应“列出该 shard 的本地 store 元数据”请求时抛出了 IOException，随后被包装成普通 ElasticsearchException 返回。
常见现象 #
- 调用 shard store 相关诊断、恢复前检查或内部元数据收集逻辑时失败。
- 失败通常只发生在个别节点上的个别分片。
- 同期可能伴随 shard path 丢失、目录损坏、权限异常或节点本地磁盘问题。
典型报错与异常栈 #
常见日志形态类似下面这样：
ElasticsearchException: Failed to list store metadata for shard [[index][0]]
Caused by: IOException: ...
2. 为什么会发生这个错误 #
要列出 shard store metadata，节点必须能打开该分片对应的本地存储路径并读取必要的文件信息。如果 shard 路径异常、目录损坏、文件不可读，或者节点本地 IO 出错，这一步就会失败。它更像“本地 shard 目录自检失败”，而不是远程通信故障。
常见原因包括：
- 分片目录缺失、损坏或结构异常。
- 节点本地磁盘出现读错误，无法列出 store 元数据。
- 分片正在被关闭、迁移或处于异常恢复状态，本地 store 暂时不可稳定访问。
- 节点文件权限或数据路径配置异常。
3. 如何排查和解决这个异常和解决这个异常 #
建议按下面的顺序排查：
- 确认失败的 shard 和节点，定位到具体数据路径。
- 检查该节点的本地目录、磁盘和系统日志，确认是否有 IO 或文件系统错误。
- 结合分片状态看它是否正在恢复、关闭或迁移。
- 必要时在健康副本上对比同一 shard 的 store 元数据读取是否正常。
- 修复本地存储问题后，再重试相关诊断或恢复操作。
排查时需要注意的问题 #
- 不要把这条错误误判成“网络连接异常”；源码里异常是由本地
listStoreMetadata(request)抛出的。 - 如果只有单节点报错，而副本正常，优先考虑节点本地数据路径问题。
- 在做人工清理前，先确认该分片是否还有健康副本可用于恢复。
4. 如何解决这个错误 #
常用修复思路 #
- 修复节点本地 shard 路径或底层磁盘问题。
- 如果分片已损坏且副本健康，可考虑用副本重建该分片。
- 对异常节点进行隔离、迁移分片或替换存储设备。
- 在执行 shard store 诊断前，先确认分片处于可稳定访问状态。
后续注意事项与推荐建议 #
- 对节点本地数据路径和磁盘做更细粒度监控，而不是只看集群级健康度。
- 对关键索引保留足够副本和可恢复快照，降低单节点 store 损坏的恢复成本。
- 定期做 shard 级恢复演练，确保 store metadata 读取链路可用。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合查看集群健康度、节点指标、索引状态、错误趋势和请求画像，帮助快速判断异常是局部问题还是系统性问题。
- INFINI Gateway 适合部署在 Elasticsearch 前面做请求观测、限流、熔断、缓存和流量治理，尤其适合定位高频错误请求、异常重试和不合理 DSL。
- 如果需要长期治理，建议把异常日志、慢查询、调用来源和变更记录统一接入监控面板，缩短从“发现问题”到“定位根因”的时间。
5. 小结 #
这条错误的重点是“节点本地 shard store 元数据列举失败”。排障要落到具体节点、具体分片和具体数据路径，而不是泛泛看集群网络。
相关错误 #
- failed-to-get-store-file-metadata-如何解决此Elasticsearch异常
- failed-to-read-shard-snapshot-file-for-如何解决此Elasticsearch异常
- 分片尚未完全恢复 - 如何解决此 Elasticsearch 异常
附：日志上下文 #
下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：
@Override
protected NodeStoreFilesMetadata nodeOperation(NodeRequest request; Task task) {
try {
return new NodeStoreFilesMetadata(clusterService.localNode(); listStoreMetadata(request));
} catch (IOException e) {
throw new ElasticsearchException("Failed to list store metadata for shard [" + request.shardId + "]"; e);
}
} private StoreFilesMetadata listStoreMetadata(NodeRequest request) throws IOException {
final ShardId shardId = request.getShardId();
