适用版本： 6.8-8.9
1. 错误异常的基本描述 #
这条 failed to list blobs 出现在 shard snapshot 相关文件列举阶段。源码中如果没有明确的 generation，Elasticsearch 会去执行 shardContainer.listBlobsByPrefix(INDEX_FILE_PREFIX) 来查找分片快照索引文件；一旦这个列举动作抛出 IOException，就会被包装成 IndexShardSnapshotFailedException(shardId, "failed to list blobs", e)。
这说明问题点不在请求解析，而在仓库中按前缀列举某类 blob 对象时失败。
常见现象 #
- 快照执行、分片 snapshot 状态收集或仓库检查中途失败。
- 只有某些 shard 或某些仓库路径出错，而不是整个仓库一定完全不可用。
- 常伴随对象存储 list 权限不足、prefix 路径异常或临时 I/O 故障。
典型报错与异常栈 #
IndexShardSnapshotFailedException[[index][0] failed to list blobs]
Caused by: IOException
2. 为什么会发生这个错误 #
Elasticsearch 需要通过前缀列举拿到 shard 容器下的索引文件，例如 index-* 这类 blob 名称。如果后端不允许列举、返回异常、prefix 错误或路径状态不一致，流程就会被中断。
常见原因包括：
- 对象存储或共享存储没有 list 权限。
- shard 对应的容器路径、prefix 或目录结构异常。
- 存储后端网络波动、超时或暂时不可用。
- 仓库元数据或 shard 目录处于不一致状态，导致列举动作失败。
3. 如何排查和解决这个异常和解决这个异常 #
建议按下面顺序排查：
- 确认失败的是哪个仓库、哪个 shard 以及哪个 prefix。
- 判断底层异常是权限问题、I/O 问题还是路径不存在。
- 核查仓库后端是否允许 list 操作，而不仅仅是读写单对象。
- 对比其他 shard 是否也存在同样的列举失败。
- 如果只影响个别 shard，重点检查其目录结构和历史操作记录。
排查时需要注意的问题 #
- 这条错误比“读取具体 blob”更早，说明连文件清单都拿不到。
- 如果 generation 已明确，代码会跳过列举，因此这条错误通常发生在需要动态探测索引文件名的路径上。
- 不要把 list 权限和 read 权限混为一谈，很多对象存储允许读单对象但限制列举。
4. 如何解决这个错误 #
常用修复思路 #
- 修复仓库后端对 list/prefix 操作的权限与策略配置。
- 检查并修正 shard 容器路径、prefix 映射或目录结构。
- 对不稳定的对象存储连接、代理或网络路径做修复和重试治理。
- 如果只有个别 shard 受影响，重点修复其仓库元数据或目录一致性问题。
借助 INFINI 产品提升排障效率 #
- INFINI Console 有助于按仓库、节点和时间线聚合 shard snapshot 失败日志。
- INFINI Gateway 适合审计运维请求与仓库访问链路。
5. 小结 #
failed to list blobs 的核心是 shard 容器里的 blob 清单无法列出。修复重点不是重试高层 snapshot API，而是恢复底层仓库 list 能力和 shard 路径一致性。
相关错误 #
- could not read repository data from index blob - 如何解决此 Elasticsearch 异常
- could not determine repository generation from root blobs - 如何解决此 Elasticsearch 异常
- failed to update snapshot in repository - 如何解决此 Elasticsearch 异常
- 检查 blob 是否存在失败 - 如何解决此 Elasticsearch 异常
附：日志上下文 #
下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：
if (generation == null) {
snapshotStatus.ensureNotAborted();
try {
blobs = shardContainer.listBlobsByPrefix(INDEX_FILE_PREFIX).keySet();
} catch (IOException e) {
throw new IndexShardSnapshotFailedException(shardId; "failed to list blobs"; e);
}
} else {
blobs = Collections.singleton(INDEX_FILE_PREFIX + generation);
}
