适用版本： 7.0-8.9
1. 错误异常的基本描述 #
cannot restore index [...] because it cannot be upgraded 表示 Elasticsearch 在执行快照恢复前置校验时，尝试验证快照中的索引元数据，但验证失败，最终抛出 SnapshotRestoreException。从源码看，它发生在真正恢复分片数据之前，属于 restore 请求的“元数据兼容性检查”阶段，而不是后面的 shard 恢复执行阶段。
这类错误的重点不是仓库读不到，也不是分片恢复中断，而是“这个索引的快照元数据无法被当前集群接受”。
常见现象 #
POST /_snapshot/{repository}/{snapshot}/_restore很快失败，通常不会进入大规模分片恢复。- 报错里会带上具体索引名，例如
cannot restore index [logs-2023.10.01] because it cannot be upgraded。 - 常见于跨大版本恢复、目标集群缺少相关插件，或快照中的旧索引设置在当前版本已不再支持。
- 如果 restore 请求里包含多个索引，往往只有个别旧索引失败，其他索引可能不受影响。
典型报错与异常栈 #
SnapshotRestoreException[[repo:snap-20260401] cannot restore index [logs-2023.10.01] because it cannot be upgraded]
Caused by: IllegalStateException / IllegalArgumentException / MapperParsingException
2. 为什么会发生这个错误 #
源码会先调用 indexMetadataVerifier.verifyIndexMetadata(...) 对快照中的索引元数据做兼容性检查。只要这一步抛出异常，就会被包装成当前这条 cannot restore index。因此它通常意味着目标集群无法接受该索引的元数据定义，而不是请求格式本身有问题。
常见原因通常包括：
- 快照来自过旧版本，索引创建版本低于当前集群可升级范围。
- 索引使用了当前集群不存在的自定义分析器、分词器、字段类型或插件能力。
- 快照中的索引设置、mapping 或兼容性参数在当前版本已废弃或不再允许恢复。
- 目标集群与源集群发行版、插件集合或功能模块不一致，导致元数据校验失败。
3. 如何排查和解决这个异常和解决这个异常 #
建议按“先确认快照版本和索引来源，再确认目标集群能否识别这些元数据”的顺序排查：
- 从错误信息中提取失败索引名和下层
cause。 - 查看快照元数据，确认快照版本、索引列表和来源环境。
- 核对目标集群是否具备该索引依赖的插件、分析器和字段类型支持。
- 判断是否属于跨大版本恢复，必要时先恢复到中间版本再做升级。
- 如果索引同名已存在，再检查是否需要先关闭目标索引或使用重命名恢复。
相关 Elasticsearch API 及调用说明 #
1. 查看快照详情 #
curl -X GET "http://localhost:9200/_snapshot/my_repo/my_snapshot?pretty"
重点确认：
- 快照来自哪个 Elasticsearch 版本。
- 目标索引是否确实包含在该快照中。
- 是否存在明显的旧版本索引或历史遗留索引。
2. 查看目标集群节点插件 #
curl -X GET "http://localhost:9200/_nodes/plugins?pretty"
如果源索引依赖自定义分析器、repository 相关组件或特定字段类型插件，这一步可以帮助确认目标集群是否缺失对应能力。
3. 使用重命名方式测试恢复 #
curl -X POST "http://localhost:9200/_snapshot/my_repo/my_snapshot/_restore?pretty" \
-H 'Content-Type: application/json' \
-d '{
"indices": "logs-2023.10.01",
"rename_pattern": "(.+)",
"rename_replacement": "restored-$1"
}'
如果目标集群已经存在同名索引，先用重命名恢复可以避免把“索引冲突”与“元数据不可升级”混在一起。
排查时需要注意的问题 #
- 这条错误发生在 restore 的前置校验阶段，不等同于
failed to restore snapshot [snapshotId]那类执行期失败。 - 如果外层只看到
cannot restore index，真正的修复方向取决于下层cause，例如版本不兼容、mapping 不兼容或插件缺失。 - 同一个快照里，只有个别历史索引失败是很常见的，不必把它误判为整个仓库损坏。
4. 如何解决这个错误 #
常用修复思路 #
- 对过旧快照采用中间版本恢复后再升级的路径，而不是直接跨越不支持的版本边界。
- 在目标集群补齐缺失插件、分析器或功能模块后再恢复。
- 如果只需要业务数据，优先排除有兼容性问题的旧索引，分批恢复。
- 对同名索引先关闭、删除或改用
rename_pattern/rename_replacement，避免恢复冲突干扰判断。
后续注意事项与推荐建议 #
- 为跨版本恢复建立“源版本 -> 中间版本 -> 目标版本”的标准升级路径。
- 对核心快照定期做恢复演练，而不是只验证快照创建成功。
- 在升级集群前盘点历史索引的创建版本和插件依赖，避免恢复时才暴露兼容性问题。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合查看 restore 失败时间线、节点插件状态和索引层面的异常分布。
- INFINI Gateway 适合沉淀 restore 请求审计，帮助回溯是谁在什么时间使用了哪些恢复参数。
5. 小结 #
cannot restore index 的核心含义是“快照中的这个索引元数据无法被当前集群升级或接受”。处理时要把注意力放在版本兼容、插件依赖和索引元数据本身，而不是一开始就把问题归因到仓库或网络。
相关错误 #
- cannot restore incompatible snapshot：快照整体版本不兼容时会更早失败
- failed to restore snapshot [snapshotId]：通过前置校验后，分片执行阶段仍可能失败
- requested feature states：恢复请求要求的 feature states 不在快照中
- snapshot could not be read：更上游的快照元数据读取失败
附：日志上下文 #
request.indexSettings(); request.ignoreIndexSettings());
try {
snapshotIndexMetadata = indexMetadataVerifier.verifyIndexMetadata(snapshotIndexMetadata;
minIndexCompatibilityVersion);
} catch (Exception ex) {
throw new SnapshotRestoreException(snapshot; "cannot restore index [" + index +
"] because it cannot be upgraded"; ex);
}
