适用版本： 7.14-8.9
1. 错误异常的基本描述 #
cannot restore index [index] because it cannot be upgraded 表示 Elasticsearch 已经拿到了目标索引的 snapshot metadata，并尝试通过 indexMetadataVerifier.verifyIndexMetadata(...) 对它做版本兼容升级校验，但校验抛出异常，最终包装成 SnapshotRestoreException。
这说明快照本身可能存在、索引名也能解析，但索引元数据结构已经无法被当前版本安全升级后再恢复。
常见现象 #
- 恢复请求在索引级校验阶段失败，通常还没进入 shard 执行恢复。
- 其他新版本创建的索引可能能恢复，只有旧索引失败。
- 常见于跨大版本恢复老索引，或 legacy index metadata 无法自动转换。
- 外层报错是
cannot be upgraded，下层cause往往更能说明具体 incompatibility。
典型报错与异常栈 #
SnapshotRestoreException: [repo:snap-20260331] cannot restore index [orders-legacy] because it cannot be upgraded
2. 为什么会发生这个错误 #
源码显示，Elasticsearch 会先尝试 convertLegacyIndex(...)，然后调用 verifyIndexMetadata(...)。只要旧索引的设置、mapping 或底层版本信息无法满足当前版本的最小兼容要求，恢复就会在这一层被拒绝。
常见原因通常包括：
- 索引创建版本过旧，超出当前版本支持的自动升级范围。
- legacy index metadata 存在当前版本已不支持的设置或结构。
- 跨越了必须先中转恢复再重建索引的升级路径。
3. 如何排查和解决这个异常和解决这个异常 #
建议按“先确认是快照级兼容还是索引级元数据升级失败，再制定中转方案”的顺序处理：
- 先确认快照本身不是 incompatible snapshot。
- 查看失败索引的创建版本与历史升级路径。
- 从下层
cause判断是 mapping、settings 还是索引版本问题。 - 评估是否需要在中间版本集群恢复后重建或 reindex，再重新快照。
相关 Elasticsearch API #
GET /_snapshot/{repository}/{snapshot}：确认快照中包含该索引。GET /：确认当前集群版本。GET /{index}/_settings与GET /{index}/_mapping：在可用历史环境中回看旧索引元数据。
排查时需要注意的问题 #
- 这条异常发生在索引级，而不是快照整体级兼容性校验。
- 不要只看外层文案，真正不兼容的字段或设置通常在
cause里。 - 如果恢复目标是迁移数据，不一定非要直接 restore，先中转 reindex 往往更稳妥。
4. 如何解决这个错误 #
常用修复思路 #
- 在兼容的中间版本集群中恢复旧索引，再重建为当前版本可接受的索引。
- 对必须长期保留的数据，提前做版本滚动重建，不要等到灾备恢复时才暴露问题。
- 对升级项目，区分快照级兼容问题与索引级升级问题，分别设计处理链路。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合结合索引版本、恢复日志和失败趋势快速定位问题索引。
- INFINI Gateway 可帮助审计失败恢复请求来源和批量重试行为。
5. 小结 #
cannot restore index [index] because it cannot be upgraded 是典型的索引元数据升级失败异常。处理关键在于明确失败点是旧索引结构本身，而不是仓库可达性或 shard 执行恢复，然后按兼容版本链做中转恢复和重建。
相关错误 #
附：日志上下文 #
try {
snapshotIndexMetadata = indexMetadataVerifier.verifyIndexMetadata(snapshotIndexMetadata, minIndexCompatibilityVersion);
} catch (Exception ex) {
throw new SnapshotRestoreException(snapshot, "cannot restore index [" + index + "] because it cannot be upgraded", ex);
}
