适用版本： 6.8-8.9
1. 错误异常的基本描述 #
empty restore source 表示某个分片已经开始进入 restore 恢复链路，但 restoreSource 为空，导致 Elasticsearch 无法知道应该从哪个快照源恢复该分片，因此抛出 IndexShardRestoreFailedException。
这类错误不在 restore 请求参数校验阶段，而是在分片级实际恢复开始时才暴露出来。
常见现象 #
- restore 请求已提交，部分分片进入恢复流程后失败。
- 主节点或数据节点日志中出现
empty restore source。 - 同一恢复任务里可能只有个别分片失败，而不是整个请求立即被拒绝。
- 常与恢复元数据不完整、cluster state 异常或恢复上下文丢失同时出现。
典型报错与异常栈 #
IndexShardRestoreFailedException: [index][0] empty restore source
2. 为什么会发生这个错误 #
分片恢复需要从 RecoverySource.SnapshotRecoverySource 获取快照、仓库和索引相关元数据。如果这个恢复源对象为空，说明当前分片进入恢复流程时，所依赖的恢复上下文没有被正确传递或已丢失。
常见原因通常包括：
- cluster state 中的 restore 元数据不完整或已发生异常变更。
- 分片恢复初始化阶段被中断，导致恢复源未正确挂到 shard recovery state 上。
- 主节点切换、恢复任务取消或状态漂移，让数据节点收到一个不完整的恢复上下文。
- 快照恢复的上游元数据本身异常，分片在真正启动恢复时才发现缺失。
3. 如何排查和解决这个异常和解决这个异常 #
建议按“先确认 restore 元数据是否完整，再判断是分片局部问题还是整个恢复上下文漂移”的顺序处理：
- 查看失败分片所在恢复任务，确认是否只有个别 shard 报错。
- 检查主节点日志和 cluster state 中 restore 元数据是否完整。
- 对照快照、索引和仓库信息，确认恢复源在请求提交时是否存在。
- 如果伴随主节点切换或恢复取消事件，优先沿时间线排查上下文是否丢失。
相关 Elasticsearch API #
GET /_recovery?active_only=true：查看正在恢复的分片及失败上下文。GET /_cluster/state：检查 restore 相关元数据。GET /_snapshot/{repository}/{snapshot}：确认源快照仍然存在且可读。
排查时需要注意的问题 #
- 这类异常已经进入 shard 恢复阶段，不要再只盯着 restore 请求体。
- 如果只是个别分片失败，重点看该 shard 的恢复状态与元数据，而不是整个仓库都出问题。
- 与
cannot delete snapshot during a restore不同，这里不是并发保护，而是恢复上下文本身缺失。
4. 如何解决这个错误 #
常用修复思路 #
- 先确认源快照和 restore 元数据完整，再重新发起恢复。
- 如果恢复过程伴随主节点切换或 cluster state 异常，先恢复集群稳定性。
- 对局部分片异常的场景，重点排查该 shard 的恢复记录和上游快照元数据。
- 避免在恢复过程中叠加大量状态变更操作，减少恢复上下文漂移风险。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合关联查看分片恢复状态、主节点日志和恢复失败时间线。
- INFINI Gateway 可帮助审计恢复请求、取消请求和相关异常调用的先后顺序。
5. 小结 #
empty restore source 的关键不是“快照不存在”，而是某个分片在进入恢复阶段时拿不到有效恢复源。处理时要围绕 restore 元数据、cluster state 和分片恢复上下文来查，而不是只看 restore API 请求参数。
相关错误 #
附：日志上下文 #
if (restoreSource == null) {
listener.onFailure(new IndexShardRestoreFailedException(shardId, "empty restore source"));
return;
}
