适用版本： 6.8-8.9
1. 错误异常的基本描述 #
snapshot should be performed only on primary 表示 Elasticsearch 在执行 shard 快照时发现当前 routing entry 不是 primary，因此立即抛出 IndexShardSnapshotFailedException。源码中这一检查发生在实际 snapshot 逻辑之前，是为了保证快照只基于主分片的一致数据视图生成。
这是一条典型的 shard 角色约束异常。
常见现象 #
- 快照任务启动后，个别 shard 直接失败。
- 失败通常出现在分片切主、重平衡或 relocation 窗口。
- 同一索引的某些分片成功，另一些因为角色变化失败。
- 相邻异常还可能出现
cannot snapshot while relocating。
典型报错与异常栈 #
IndexShardSnapshotFailedException: [index][0] snapshot should be performed only on primary
2. 为什么会发生这个错误 #
快照必须从主分片读取，以避免副本落后或状态不一致带来的数据风险。如果触发 snapshot 时该 shard 已不是 primary，或者主副本角色刚刚发生切换，Elasticsearch 会拒绝继续执行。
常见原因通常包括：
- 快照过程中发生主分片切换。
- 分片正在 relocating，角色信息处于变化窗口。
- 集群抖动导致 snapshot 任务落到了非 primary shard 上。
3. 如何排查和解决这个异常和解决这个异常 #
建议按“先确认失败 shard 当时是不是 primary，再判断是否伴随 relocation 或主从切换”的顺序处理：
- 记录失败的
shardId和节点。 - 查看快照失败时间点该 shard 的 primary 归属。
- 检查是否同时存在 relocation、reroute 或 master 变更事件。
- 若只是短时切换，等 shard 稳定后重新发起 snapshot。
相关 Elasticsearch API #
GET /_cat/shards/{index}：查看主副本分布与当前状态。GET /_cluster/allocation/explain：分析 shard 为什么处于迁移或不稳定状态。GET /_snapshot/_status：确认失败 shard 列表。
排查时需要注意的问题 #
- 这条异常和
snapshot is not allowed不同，一个是角色约束，一个是 shard state 约束。 - 如果频繁遇到该问题，说明快照窗口和分片迁移窗口重叠过多。
- 不要只看最终哪个节点是 primary，要看失败当时的瞬时状态。
4. 如何解决这个错误 #
常用修复思路 #
- 避开集群重平衡、节点维护和大规模迁移时段执行快照。
- 让 primary 分片状态稳定后再重试 snapshot。
- 针对频繁切主的索引，优先解决集群稳定性和主分片波动问题。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合关联查看 shard 角色切换、快照失败点和节点事件。
- INFINI Gateway 可帮助识别快照请求是否集中打在集群不稳定窗口。
5. 小结 #
snapshot should be performed only on primary 的核心是 shard 角色不满足快照要求。解决方法不是盯着仓库配置，而是确认 primary 归属与 snapshot 执行窗口是否冲突。
相关错误 #
- 不允许创建快照：shard 状态本身不允许获取 snapshot commit
- Failed to snapshot：分片级 snapshot 执行中的包装异常
- 快照失败：更上层的 snapshot 执行失败包装
- 相同名称快照正在进行中：snapshot 入口的并发冲突异常
附：日志上下文 #
if (indexShard.routingEntry().primary() == false) {
throw new IndexShardSnapshotFailedException(shardId, "snapshot should be performed only on primary");
}
