适用版本： 6.8-8.9
1. 错误异常的基本描述 #
Unknown alias name was passed to alias filter 表示 Elasticsearch 在构建别名过滤器时，使用了不存在的别名名称。
从源码可见，这个异常在 QueryShardContext 的别名过滤器构建路径中抛出，当别名在索引的别名列表中找不到时触发。
典型报错 #
InvalidAliasNameException: Unknown alias name was passed to alias filter
2. 为什么会发生这个错误 #
- 别名不存在：查询中引用的别名未在索引上定义。
- 别名被删除：别名在查询执行期间被删除。
- 别名拼写错误：别名名称拼写错误。
- 跨索引查询错误：在跨索引查询中使用了某个索引上不存在的别名。
3. 排查步骤 #
- 检查索引别名：
GET /_cat/aliases GET /my-index/_alias - 确认别名存在：验证查询中使用的别名是否存在于目标索引。
- 检查别名拼写：确认别名名称拼写正确。
- 查看集群状态：确认集群状态正常，无正在进行的别名变更操作。
4. 修复建议 #
方案一：创建缺失的别名 #
如果别名不存在，先创建别名：
POST /_aliases
{
"actions": [
{
"add": {
"index": "my-index",
"alias": "my-alias"
}
}
]
}
方案二：修正别名名称 #
确保查询中使用正确的别名名称。
方案三：使用索引名称 #
如果不需要别名过滤，直接使用索引名称查询。
方案四：检查跨索引查询 #
对于跨索引查询，确保所有索引都有该别名，或使用通配符索引模式。
5. 小结 #
Unknown alias name was passed to alias filter 通常意味着查询中引用了不存在的别名。排查时应优先检查别名定义和拼写。
相关错误 #
- invalid-alias-name-exception-how-to-solve-this-elasticsearch-exception
- aliases-not-found-exception-how-to-solve-this-elasticsearch-exception
- index-not-found-exception-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
};
if (aliasNames.length == 1) {
AliasMetadata alias = aliases.get(aliasNames[0]);
if (alias == null) {
// This shouldn't happen unless alias disappeared after filteringAliases was called.
throw new InvalidAliasNameException(index, aliasNames[0], "Unknown alias name was passed to alias Filter");
}
return parserFunction.apply(alias);
} else {
// we need to bench here a bit; to see maybe it makes sense to use OrFilter
BoolQueryBuilder combined = new BoolQueryBuilder();
