---
title: "快照只能在主分片上执行 - 如何解决此Elasticsearch异常"
date: 2026-03-17
lastmod: 2026-03-17
description: "snapshot should be performed only on primary 表示当前执行 snapshot 的 shard 不是 primary，Elasticsearch 会直接拒绝继续快照。"
tags: ["快照", "主分片", "IndexShardSnapshotFailedException"]
summary: "适用版本： 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 会拒绝继续执行。"
---


> **适用版本：** 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`。

### 典型报错与异常栈

```text
IndexShardSnapshotFailedException: [index][0] snapshot should be performed only on primary
```

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

快照必须从主分片读取，以避免副本落后或状态不一致带来的数据风险。如果触发 snapshot 时该 shard 已不是 primary，或者主副本角色刚刚发生切换，Elasticsearch 会拒绝继续执行。

常见原因通常包括：

- 快照过程中发生主分片切换。
- 分片正在 relocating，角色信息处于变化窗口。
- 集群抖动导致 snapshot 任务落到了非 primary shard 上。

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

建议按“先确认失败 shard 当时是不是 primary，再判断是否伴随 relocation 或主从切换”的顺序处理：

1. 记录失败的 `shardId` 和节点。
2. 查看快照失败时间点该 shard 的 primary 归属。
3. 检查是否同时存在 relocation、reroute 或 master 变更事件。
4. 若只是短时切换，等 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](https://docs.infinilabs.com/console/main/) 适合关联查看 shard 角色切换、快照失败点和节点事件。
- [INFINI Gateway](https://docs.infinilabs.com/gateway/main/) 可帮助识别快照请求是否集中打在集群不稳定窗口。

## 5. 小结

`snapshot should be performed only on primary` 的核心是 shard 角色不满足快照要求。解决方法不是盯着仓库配置，而是确认 primary 归属与 snapshot 执行窗口是否冲突。

## 相关错误

- [不允许创建快照：shard 状态本身不允许获取 snapshot commit](/knowledge-base/elasticsearch_error/snapshot-is-not-allowed-how-to-solve-this-elasticsearch-exception/)
- [Failed to snapshot：分片级 snapshot 执行中的包装异常](/knowledge-base/elasticsearch_error/failed-to-snapshot-how-to-solve-this-elasticsearch-exception/)
- [快照失败：更上层的 snapshot 执行失败包装](/knowledge-base/elasticsearch_error/snapshot-failed-how-to-solve-this-elasticsearch-exception/)
- [相同名称快照正在进行中：snapshot 入口的并发冲突异常](/knowledge-base/elasticsearch_error/snapshot-with-the-same-name-is-already-in-progress-how-to-solve-this-elasticsearch-exception/)

## 附：日志上下文

```java
if (indexShard.routingEntry().primary() == false) {
	throw new IndexShardSnapshotFailedException(shardId, "snapshot should be performed only on primary");
}
```