适用版本： 6.8-8.9
1. 错误异常的基本描述 #
快照不是对任意分片副本随便抓一份数据，而是要求在稳定的主分片视图上执行。源码明确规定：如果主分片当前正处于 relocation 过程中，就直接抛出 cannot snapshot while relocating，避免拿到不一致的分片状态。
常见现象 #
- 手动执行快照时，只有部分分片失败。
- 集群同时在做 rebalance、节点下线迁移、磁盘水位驱动的 relocation。
- 错误通常与
snapshot should be performed only on primary、RECOVERING等分片状态检查出现在一起。
典型报错与异常栈 #
IndexShardSnapshotFailedException[... cannot snapshot while relocating]
2. 为什么会发生这个错误 #
主分片 relocation 期间，分片数据和操作上下文正在从旧节点切换到新节点。如果此时执行快照，可能拿到尚未完全稳定的分片视图，因此 Elasticsearch 直接禁止这类操作。
常见触发原因包括：
- 节点扩缩容或故障恢复导致大量主分片迁移。
- 磁盘水位触发 shard relocation。
- 手动 reroute 或集群再平衡与快照任务时间重叠。
- 索引刚创建或分片仍在恢复阶段，尚未稳定。
3. 如何排查和解决这个异常和解决这个异常 #
- 先查看相关分片是否正在迁移：
GET /_cat/shards?v
GET /_cluster/health
- 使用
/_cluster/allocation/explain查看目标分片为何处于 relocation。 - 观察当前是否有节点加入/离开、磁盘水位告警、手动 reroute 操作。
- 等待分片回到稳定状态后再重新执行快照。
- 如果快照任务长期与 relocation 冲突，调整快照执行窗口。
排查时需要注意的问题 #
- 这不是仓库后端错误，而是分片状态保护。
- 如果集群持续处于重平衡状态，简单重试往往仍会失败。
- 要优先解决 relocation 背后的资源或节点问题，而不是反复触发快照。
4. 如何解决这个错误 #
常用修复思路 #
- 等待 relocation 完成，再重新发起快照。
- 缓解导致频繁迁移的根因，例如磁盘水位、节点抖动、资源不足。
- 把大规模节点变更和快照计划错峰执行。
- 对关键索引快照增加前置健康检查，确保主分片稳定后再执行。
相关 Elasticsearch API #
GET /_cat/shards?v：查看分片状态与 relocation 情况。GET /_cluster/allocation/explain：分析为什么发生迁移。PUT /_cluster/settings：必要时调整 rebalance 或水位相关设置。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合联动观察分片迁移、节点资源和快照失败时间线。
- INFINI Gateway 可帮助识别是否存在高峰时段集中触发快照任务。
5. 小结 #
cannot snapshot while relocating 是一个明确的分片状态保护异常。只要主分片还在迁移，Elasticsearch 就不会允许对它做快照。优先稳定分片路由，再做快照，才是正确处理顺序。
附：日志上下文 #
if (indexShard.routingEntry().primary() == false) {
throw new IndexShardSnapshotFailedException(shardId, "snapshot should be performed only on primary");
}
if (indexShard.routingEntry().relocating()) {
throw new IndexShardSnapshotFailedException(shardId, "cannot snapshot while relocating");
}
