适用版本： 7.12-8.9
1. 错误异常的基本描述 #
某些仓库内部流程不会只按仓库名称工作，而是按仓库元数据里的 UUID 定位具体仓库实例。如果遍历当前已注册仓库后，仍找不到对应 UUID，就会抛出 uuid [repositoryUuid]; original name [originalName] 形式的 RepositoryMissingException。
常见现象 #
- 仓库名称看起来还在，但某些内部快照/恢复流程仍然失败。
- 日志显示原始仓库名
originalName，但当前集群中的仓库 UUID 已变化。 - 常见于删除后重建同名仓库、切换后端路径、跨集群迁移仓库定义之后。
典型报错与异常栈 #
org.elasticsearch.repositories.RepositoryMissingException: uuid [abc123]; original name [prod-backup]
2. 为什么会发生这个错误 #
从源码看，Elasticsearch 会遍历当前已注册的 repositories.values()，按 repository.getMetadata().uuid() 匹配目标 UUID。如果没有任何一个仓库匹配，就会抛出该异常。这说明当前内存中的仓库注册信息，与触发请求时引用的仓库身份并不一致。
常见原因包括：
- 仓库被删除后又以同名重新创建，名称相同但 UUID 已变化。
- 集群状态中仍残留旧任务、旧恢复流程或旧快照流程，引用了历史仓库 UUID。
- 多环境迁移时直接复用了名字，但底层仓库实际上不是同一个。
- 主节点切换或集群状态恢复期间，仓库元数据出现短暂不一致。
3. 如何排查和解决这个异常和解决这个异常 #
- 先列出当前仓库定义，确认目标仓库是否仍存在：
GET /_snapshot/_all
- 对照异常中的
original name，确认该仓库是否近期被删除、重建或改过配置。 - 检查是否有恢复任务、快照任务、ILM/SLM 流程仍在引用旧仓库上下文。
- 如果你做过同名仓库重建，要特别注意：名称一致不代表 UUID 一致。
- 若异常出现在主节点切换后，结合集群日志检查是否存在仓库注册信息刷新延迟或元数据变更冲突。
排查时需要注意的问题 #
- 不要只看仓库名字。这个异常明确说明问题在“仓库身份”而不是显示名称。
- 同名重建仓库是最常见诱因之一，尤其在运维脚本用“先删后建”方式变更配置时。
- 如果有长生命周期任务，变更仓库定义前要先确认没有旧任务仍在执行。
4. 如何解决这个错误 #
常用修复思路 #
- 如果仓库是刚重建的，停止仍引用旧 UUID 的任务，并重新发起新的快照/恢复操作。
- 尽量避免在有活动任务时删除再重建同名仓库。
- 如果只是为了改设置，优先使用受支持的更新方式，避免不必要地重建仓库身份。
- 集群状态恢复稳定后重新验证仓库定义，确认旧上下文已清理干净。
相关 Elasticsearch API #
GET /_snapshot/_all：查看当前所有仓库定义。GET /_tasks：排查是否仍有仓库相关任务在执行。GET /_cluster/state/metadata：必要时检查仓库元数据在集群状态中的表现。
借助 INFINI 产品提升排障效率 #
- INFINI Console 可联合查看任务、节点日志和仓库定义变更记录。
- INFINI Gateway 适合审计到底是谁触发了仓库删除重建流程。
5. 小结 #
uuid [repositoryUuid]; original name [originalName] 说明当前请求引用的是一个已经不在集群注册表中的仓库身份。名字相同并不能消除这个问题，关键要排查是否发生过仓库重建、任务残留或元数据切换。
附：日志上下文 #
for (Repository repository : repositories.values()) {
if (repository.getMetadata().uuid().equals(repositoryUuid)) {
return repository;
}
}
throw new RepositoryMissingException("uuid [" + repositoryUuid + "]; original name [" + originalName + "]");
