适用版本： 6.8-7.3
1. 错误异常的基本描述 #
cannot restore incompatible snapshot 表示 Elasticsearch 在真正进入 restore 之前，就已经从 RepositoryData 中判断出该快照属于 incompatibleSnapshotIds，因此直接拒绝恢复并抛出 SnapshotRestoreException。
这类错误不是执行失败，而是恢复入口的兼容性校验失败。
常见现象 #
POST /_snapshot/{repository}/{snapshot}/_restore立即失败，没有进入 shard 恢复阶段。- 日志里通常同时包含 repository 名称和 snapshot 名称。
- 在同一仓库中，其他新版本快照可能可以恢复，只有这个旧快照不行。
- 常见于跨大版本升级后，尝试直接恢复过旧格式的快照。
典型报错与异常栈 #
SnapshotRestoreException: [repo:snap-old] cannot restore incompatible snapshot
2. 为什么会发生这个错误 #
Elasticsearch 在处理恢复请求时会先读取仓库元数据。若目标快照出现在 repositoryData.getIncompatibleSnapshotIds() 中，就说明它已经被识别为当前集群版本不支持直接恢复的快照格式。
常见原因通常包括：
- 快照由更旧的大版本 Elasticsearch 创建，当前版本无法直接识别或升级。
- 中间升级链路缺失，导致必须先在兼容版本中恢复再重新快照。
- 仓库里同时保留了兼容和不兼容快照，误选了旧快照名。
3. 如何排查和解决这个异常和解决这个异常 #
建议按“先确认快照是否被官方判定为 incompatible，再制定中转恢复方案”的顺序处理：
- 查看恢复请求里的仓库名和快照名是否正确。
- 列出仓库快照，确认目标快照是否确实为旧版本产物。
- 检查当前集群版本与快照创建版本之间是否存在跨代跳跃。
- 评估是否需要先在中间兼容版本恢复，再重新生成新快照。
相关 Elasticsearch API #
GET /_snapshot/{repository}/_all：查看仓库中的快照清单。GET /_snapshot/{repository}/{snapshot}：确认目标快照详情与版本信息。GET /：核对当前集群版本。
排查时需要注意的问题 #
- 这条异常发生得很早，通常还没进入索引校验或 shard 恢复。
- 不要把它和
cannot restore index ... because it cannot be upgraded混为一谈，前者是快照级不兼容，后者是索引元数据升级失败。 - 如果仓库里存在同名近似快照，先确认没有选错对象。
4. 如何解决这个错误 #
常用修复思路 #
- 改用当前版本可兼容的快照恢复。
- 若必须使用旧快照，先准备一个中间兼容版本集群进行恢复和重建快照。
- 在升级迁移方案中显式校验 snapshot compatibility，避免临时恢复时才发现断层。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合集中查看快照元数据、版本差异与恢复失败记录。
- INFINI Gateway 可帮助审计是谁发起了失败的恢复请求，以及请求频次。
5. 小结 #
cannot restore incompatible snapshot 是恢复入口的兼容性拦截，不是 restore 过程中的偶发执行失败。处理重点是确认快照创建版本与当前集群版本的关系，并按兼容链路设计中转恢复方案。
相关错误 #
- 索引未完全快照无法恢复：快照可见但索引快照并不完整
- 无法恢复部分索引：快照通过了入口校验，但恢复策略本身不允许完整恢复
- 恢复失败：通过前置校验后，在 restore 执行阶段失败
- 无法恢复索引，因为已有打开索引：恢复入口的相邻索引级校验异常
附：日志上下文 #
final Optional incompatibleSnapshotId = repositoryData.getIncompatibleSnapshotIds()
.stream()
.filter(s -> snapshotName.equals(s.getName()))
.findFirst();
if (incompatibleSnapshotId.isPresent()) {
throw new SnapshotRestoreException(repositoryName, snapshotName, "cannot restore incompatible snapshot");
}
