适用版本： 6.8-8.9
1. 错误异常的基本描述 #
failed to restore snapshot [snapshotId] 表示 Elasticsearch 已经为某个 shard 启动了恢复执行流程，但在真正从仓库恢复该分片数据时失败，最终抛出 IndexShardRestoreFailedException。这说明问题已经晚于“快照能否读取”“分片快照文件能否定位”的阶段，真正卡在了恢复执行本身。
它是 restore 链路里更靠后、更接近分片落盘恢复的失败信号。
常见现象 #
- restore 请求已接受，部分 shard 在执行中失败。
- 节点日志中会看到具体
snapshotId与shardId。 - 可能伴随 store closing、恢复取消、仓库读取失败或文件恢复中断等下层异常。
- 某些 shard 成功、某些 shard 失败，最终导致索引恢复不完整。
典型报错与异常栈 #
IndexShardRestoreFailedException: [index][0] failed to restore snapshot [snap-20260331]
2. 为什么会发生这个错误 #
当 restore 执行线程真正去恢复 shard 内容时，任何下层失败都会被包装成这条异常，例如读取仓库数据失败、恢复过程被取消、store 状态异常，或者恢复文件阶段中断。
常见原因通常包括：
- 分片恢复过程中仓库对象读取失败。
- shard store 正在关闭或状态不允许继续恢复。
- 前置的 shard snapshot metadata 虽然存在，但恢复到本地时出错。
- 恢复线程被取消、中断，或节点状态变化导致恢复半途失败。
3. 如何排查和解决这个异常和解决这个异常 #
建议按“先看它包裹的下层 cause，再判断是 restore 上下文问题还是仓库/节点执行问题”的顺序处理：
- 查看
IndexShardRestoreFailedException下层真实cause。 - 确认失败前该 shard 是否已成功定位到快照和 shard snapshot file。
- 检查失败节点的 store 状态、磁盘、线程池和恢复任务日志。
- 如果只是少量 shard 失败，围绕具体 shard 和节点做局部排查。
相关 Elasticsearch API #
GET /_recovery：查看失败 shard 的恢复阶段和原因。GET /_cluster/allocation/explain：判断失败后分片为何未继续分配或恢复。GET /_snapshot/{repository}/{snapshot}：确认源快照仍可见且完整。
排查时需要注意的问题 #
- 这条异常本身是执行阶段包装层，真正原因通常藏在下层
cause。 - 不要跳过前置链路判断，先确认快照整体、shard file 和 restore source 是否都已正确获取。
- 如果节点正在关闭或 shard store 状态异常，单纯重试恢复可能不会成功。
4. 如何解决这个错误 #
常用修复思路 #
- 先锁定下层 cause，再按仓库读取、节点状态或恢复中断分别处理。
- 恢复节点稳定性和 store 可用性后再重试 restore。
- 如果个别 shard 对应快照数据已损坏，改用其他可用快照恢复。
- 对频繁失败的恢复流程建立分片级监控，而不是只看 restore 请求成功提交与否。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合关联查看 shard 恢复状态、节点异常与仓库读取错误。
- INFINI Gateway 可帮助观察是否存在重复恢复、取消恢复或异常重试流量。
5. 小结 #
failed to restore snapshot [snapshotId] 说明 restore 已进入分片执行阶段。真正要解决的往往不是 restore 请求本身，而是包裹在这条异常内部的具体恢复失败原因，以及对应的 shard、节点或仓库执行问题。
相关错误 #
- 快照无法读取：restore 前的整体快照元数据读取失败
- 无法读取分片快照文件：restore 前的 shard snapshot metadata 读取失败
- 无法找到分片的最新快照：恢复前定位 shard snapshot 失败
- 空恢复源：进入执行前恢复上下文缺失的相邻异常
附：日志上下文 #
final ActionListener<Void> restoreListener = listener.delegateResponse(
(l, e) -> l.onFailure(new IndexShardRestoreFailedException(shardId, "failed to restore snapshot [" + snapshotId + "]", e))
);
