---
title: "空恢复源 – 如何解决此 Elasticsearch 异常"
date: 2026-03-27
lastmod: 2026-03-27
description: "empty restore source 表示分片进入 restore 恢复阶段时没有拿到有效的 restore source，本文结合 IndexShardRestoreFailedException 说明原因、排查与修复方法。"
tags: ["快照恢复", "recovery source", "IndexShardRestoreFailedException"]
summary: "适用版本： 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 元数据是否完整，再判断是分片局部问题还是整个恢复上下文漂移”的顺序处理："
---


> **适用版本：** 6.8-8.9

## 1. 错误异常的基本描述

`empty restore source` 表示某个分片已经开始进入 restore 恢复链路，但 `restoreSource` 为空，导致 Elasticsearch 无法知道应该从哪个快照源恢复该分片，因此抛出 `IndexShardRestoreFailedException`。

这类错误不在 restore 请求参数校验阶段，而是在分片级实际恢复开始时才暴露出来。

### 常见现象

- restore 请求已提交，部分分片进入恢复流程后失败。
- 主节点或数据节点日志中出现 `empty restore source`。
- 同一恢复任务里可能只有个别分片失败，而不是整个请求立即被拒绝。
- 常与恢复元数据不完整、cluster state 异常或恢复上下文丢失同时出现。

### 典型报错与异常栈

```text
IndexShardRestoreFailedException: [index][0] empty restore source
```

## 2. 为什么会发生这个错误

分片恢复需要从 `RecoverySource.SnapshotRecoverySource` 获取快照、仓库和索引相关元数据。如果这个恢复源对象为空，说明当前分片进入恢复流程时，所依赖的恢复上下文没有被正确传递或已丢失。

常见原因通常包括：

- cluster state 中的 restore 元数据不完整或已发生异常变更。
- 分片恢复初始化阶段被中断，导致恢复源未正确挂到 shard recovery state 上。
- 主节点切换、恢复任务取消或状态漂移，让数据节点收到一个不完整的恢复上下文。
- 快照恢复的上游元数据本身异常，分片在真正启动恢复时才发现缺失。

## 3. 如何排查和解决这个异常和解决这个异常

建议按“先确认 restore 元数据是否完整，再判断是分片局部问题还是整个恢复上下文漂移”的顺序处理：

1. 查看失败分片所在恢复任务，确认是否只有个别 shard 报错。
2. 检查主节点日志和 cluster state 中 restore 元数据是否完整。
3. 对照快照、索引和仓库信息，确认恢复源在请求提交时是否存在。
4. 如果伴随主节点切换或恢复取消事件，优先沿时间线排查上下文是否丢失。

### 相关 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](https://docs.infinilabs.com/console/main/) 适合关联查看分片恢复状态、主节点日志和恢复失败时间线。
- [INFINI Gateway](https://docs.infinilabs.com/gateway/main/) 可帮助审计恢复请求、取消请求和相关异常调用的先后顺序。

## 5. 小结

`empty restore source` 的关键不是“快照不存在”，而是某个分片在进入恢复阶段时拿不到有效恢复源。处理时要围绕 restore 元数据、cluster state 和分片恢复上下文来查，而不是只看 restore API 请求参数。

## 相关错误

- [集群中恢复进程已在运行：恢复入口阶段的并发保护异常](/knowledge-base/elasticsearch_error/restore-process-is-already-running-in-this-cluster-how-to-solve-this-elasticsearch-exception/)
- [无法恢复部分索引：restore 执行过程中更上层的失败表现](/knowledge-base/elasticsearch_error/cannot-restore-partial-index-how-to-solve-this-elasticsearch-exception/)
- [恢复被取消：恢复链路中断时的相邻异常](/knowledge-base/elasticsearch_error/recovery-was-canceled-reason-reason-how-to-solve-this-elasticsearch-exception/)
- [恢复快照文件已取消：文件恢复阶段的相邻分支](/knowledge-base/elasticsearch_error/recover-snapshot-files-cancelled-how-to-solve-this-elasticsearch-exception/)

## 附：日志上下文

```java
if (restoreSource == null) {
	listener.onFailure(new IndexShardRestoreFailedException(shardId, "empty restore source"));
	return;
}
```