适用版本： 7.x-8.x
1. 错误异常的基本描述 #
failed to get roles that already exist; skipping role import 表示导入工具已经成功解析了本地角色定义文件，但在连接目标集群查询“哪些角色已经存在”这一步失败，因此放弃继续导入角色。
这意味着问题不一定在角色文件本身，更可能出在访问目标集群、认证授权或安全配置链路上。
常见现象 #
- 角色迁移或初始化命令执行中断，日志提示跳过角色导入。
- 本地角色文件可以被正常解析，但目标集群中没有新增角色。
- 日志中可能伴随认证失败、TLS 异常、连接超时或权限不足。
2. 为什么会发生这个错误 #
从日志片段看，代码先调用 FileRolesStore.parseRoleDescriptors 解析本地角色文件，然后调用 getRolesThatExist(...) 查询目标集群。如果这个查询抛异常，就会包装成当前错误。
常见原因包括：
- 目标 Elasticsearch 集群不可达或连接参数错误。
- 执行导入的账号没有读取角色信息的权限。
- TLS/证书配置不正确，导致安全连接建立失败。
- 导入工具所用环境参数、代理或节点地址配置错误。
3. 如何排查和解决这个异常和解决这个异常 #
- 先确认本地角色文件本身可解析，避免把格式问题和连接问题混为一谈。
- 检查导入工具连接的 Elasticsearch 地址、认证方式和证书配置。
- 验证当前账号是否具备读取安全角色和执行导入的权限。
- 在目标集群侧查看安全审计日志，确认是否发生认证拒绝或授权失败。
- 如果通过代理或网关访问集群，确认请求没有被中间层拦截或改写。
4. 如何解决这个错误 #
常用修复思路 #
- 修正导入工具的连接地址、用户名密码或 API Key 配置。
- 为执行导入的账号补齐读取和写入角色所需权限。
- 修复 TLS 信任链、证书文件或主机名校验问题。
- 在确认连通性正常后重新执行角色导入，避免误以为角色文件有问题。
5. 小结 #
这个异常的关键不是“导入失败”，而是“导入前的已存在角色检查失败”。优先验证目标集群访问链路，比反复修改角色文件更有效。
相关错误 #
- failed-to-get-users-that-already-exist-skipping-user-import：已存在用户检查失败
- failed-to-parse-role：角色定义解析失败
- failed-to-load-role-query：角色查询加载失败
- could-not-read-realm-realmtype-realmname-role-mappings-file：角色映射文件读取失败
附：日志上下文 #
Maproles = FileRolesStore.parseRoleDescriptors(rolesFile; logger; true; Settings.EMPTY; null);
SetexistingRoles;
try {
existingRoles = getRolesThatExist(terminal; env.settings(); env; options);
} catch (Exception e) {
throw new ElasticsearchException("failed to get roles that already exist; skipping role import"; e);
}
if (rolesToMigrate.length == 0) {
rolesToMigrate = roles.keySet().toArray(new String[roles.size()]);
}
for (String roleName : rolesToMigrate) {
