CANN HCCL 环境变量配置异常（EI0001）故障定位与解决指南

CANN HCCL 环境变量配置异常（EI0001）故障定位与解决指南

【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl

HCCL（Huawei Collective Communication Library）在通信域初始化阶段会解析大量环境变量，当其中任一变量取值不合法时，会在日志中打印EI0001（Config_Error_Invalid_Environment_Variable）故障码。本文以 CANN/hccl 开源仓库的故障诊断文档为骨架，结合仓库源码，系统讲解 EI0001 错误的产生机制、日志特征、通用定位思路，以及 HCCL_RDMA_SL、HCCL_SOCKET_IFNAME、IP Family 不一致等常见场景的完整排查与解决方法。读完本文，你将能够根据业务日志中的错误关键字快速锁定具体出问题的环境变量，并依据日志给出的建议范围完成修正。

EI0001 是什么：HCCL 环境变量配置异常

在业务的日志中出现EI0001故障码，意味着HCCL 的环境变量配置异常。EI0001 对应的完整错误描述为Config_Error_Invalid_Environment_Variable，属于 HCCL 通信域初始化（comm domain init）阶段的环境变量配置类错误。该错误在整个故障诊断体系中位于“通信域初始化阶段”下，与 rank table 文件加载失败（EI0004）、集群信息协商失败（EI0015）等并列，具体目录结构见 故障诊断 README。

从源码角度看，HCCL 在InitEnvConfig()函数中集中解析一批环境变量（入口位于 alg_env_config.cc），每个变量的解析结果都会通过RPT_ENV_ERR宏上报错误码：

HcclResult InitEnvConfig() { std::lock_guard<std::mutex> lock(g_algEnvConfigMutex); // 解析算子展开模式 HcclResult ret = ParseOpExpansion(); RPT_ENV_ERR( ret != HCCL_SUCCESS, "EI0001", std::vector<std::string>({"value", "env", "expect"}), std::vector<std::string>({GetEnv("HCCL_OP_EXPANSION_MODE"), "HCCL_OP_EXPANSION_MODE", "should be \"AI_CPU\""})); ... }

RPT_ENV_ERR宏定义于 adapter_error_manager_pub.h，其上报参数包含三组键值：value（用户实际配置的值）、env（出问题的环境变量名）、expect（期望/合法的取值说明），这正是日志与上报信息中“环境变量名称、错误原因、合理配置范围”三个要素的来源：

#define RPT_ENV_ERR(result, error_code, key, value) \ do { \ if (UNLIKELY(result) && RptEnvErr != nullptr) { \ RptEnvErr(error_code, key, value); \ } \ } while (0)

从源码结构可以推断：EI0001 是一个可追溯、可自解释的错误码——错误日志中会直接给出变量名、错误值与期望范围，定位时无需猜测。

通用定位思路

EI0001 的定位遵循以下通用路径（见 环境变量配置异常（EI0001）定位思路）：

1. 在业务日志中搜索故障码：查找关键字EI0001。
2. 读取错误详情：一般情况下，日志的 ERROR MESSAGE 和 CANN 日志中会显示：
   • 配置异常的环境变量名称；
   • 错误原因；
   • 合理的配置范围。
3. 按建议调整：依据日志打印的建议调整环境变量取值。
4. 仍有疑问时查阅环境变量参考：参照 环境变量参考，该文档按功能、性能、网络、调试、可靠性、安全等维度分类收录了全部 HCCL 环境变量说明。

该目录还提供了 EI0001 场景入口页 环境变量配置异常（EI0001），汇总了本错误的定位思路与常见场景文档。

常见场景一：HCCL_RDMA_SL 配置错误

问题现象

在打印日志中存在关键字EI0001或Value *** for environment variable *** is invalid，示例如下：

[PID:3729526]2025-10-23-17:30:40.098.984Config_Error_Invalid_Environment_Variable(EI0001): Value 1000 for environment variable HCCL_RDMA_SL is invalid. Expected value : range[0, 7].

底层报错日志

针对 Atlas A3 训练/推理系列产品、Atlas A2 训练/推理系列产品、Atlas 训练系列产品、Atlas 推理系列产品，CANN 日志的 ERROR 日志中存在关键字externalinput.cc，表示是在读取环境变量配置时报错。报错示例如下：

[ERROR]HCCL(3729526,python3.11):2025-10-23-17:30:40.098.973 [externalinput.cc:963] [3729526][Parse][rdmaServerLevel]HCCL_RDMA_SL[1000] is invalid. except: [0, 7] [ERROR]HCCL(3729526,python3.11):2025-10-23-17:30:40.099.058 [externalinput.cc:169] [3729526][InitGroupStage][EnvConfig]errNo[0x0000000005000001] In init env variable param, parse HCCL_RDMA_SL failed. errno[1] [ERROR]HCCL(3729526,python3.11):2025-10-23-17:30:40.099.063 [externalinput.cc:47] [3729526][InitExternalInput]call trace: hcclRet -> 1 [ERROR]HCCL(3729526,python3.11):2025-10-23-17:30:40.099.068 [op_base.cc:866] [3729526][HcclGetRootInfo]call trace: hcclRet -> 1

从日志链可以看出完整的报错链路：Parse阶段发现取值越界（HCCL_RDMA_SL[1000] is invalid. except: [0, 7]）→InitGroupStage环境变量解析失败（errno 1）→InitExternalInput返回错误 → 上层HcclGetRootInfo调用失败。

可能的原因及解决方法

环境变量配置参数不符合要求。HCCL_RDMA_SL用于配置 RDMA 的服务等级（Service Level），合法取值范围为[0, 7]，示例中配置为1000明显越界。请基于日志打印的建议调整取值范围，具体参数语义可参照 HCCL_RDMA_SL 及 网络相关环境变量。如果仍然有疑问，请参照对应的 环境变量参考。

常见场景二：HCCL_SOCKET_IFNAME 配置错误

问题现象

在 CANN 日志中存在关键字get host ip fail by socket Ifname，示例如下：

[ERROR] HCCL(925892,alltoall_test):2025-10-28-16:34:59.634.432 [sal.cc:501] [925892][InitGroupStage][EnvConfig]set ifname to [abc] by HCCL_SOCKET_IFNAME, but not found in the environment, ifnames in the environment is as follows [ERROR] HCCL(925892,alltoall_test):2025-10-28-16:34:59.634.437 [sal.cc:504] [925892][InitGroupStage][EnvConfig]get host ip fail by socket Ifname. name[lo] ip[127.10.0.1%lo] [ERROR] HCCL(925892,alltoall_test):2025-10-28-16:34:59.634.441 [sal.cc:504] [925892][InitGroupStage][EnvConfig]get host ip fail by socket Ifname. name[enp] ip[127.10.0.2%enp] [ERROR] HCCL(925892,alltoall_test):2025-10-28-16:34:59.634.447 [sal.cc:504] [925892][InitGroupStage][EnvConfig]get host ip fail by socket Ifname. name[docker0] ip[172.17.0.1%docker0]

注意：该报错链路位于sal.cc的系统抽象层（SAL，System Abstraction Layer），属于 HCCL 底层平台适配模块对网卡信息的查询逻辑。

问题根因

通过HCCL_SOCKET_IFNAME环境变量指定了 Host 网卡，但在当前的环境上没有找到对应的网卡。若为容器场景，需指定容器内可用的 Host 网卡——容器内看到的网卡列表与宿主机不同，直接沿用宿主机网卡名（如enp）在容器内可能无法解析。报错日志列举了当前环境上查询到的全部 Host 网卡（示例中为lo、enp、docker0），供比对确认。

解决方法

修改HCCL_SOCKET_IFNAME环境变量，指定为环境上确实存在的 Host 网卡。可以从报错日志中“ifnames in the environment is as follows”之后列出的网卡中选择其一。参数说明参见 HCCL_SOCKET_IFNAME。

常见场景三：IP Family 校验不一致（EI0001）

该场景虽同样上报 EI0001，但属于集群信息校验阶段的多 rank 一致性校验错误。

问题现象

在 CANN 日志中存在关键字rank\[\*\] device ip family\[2\] is not same as others\[\*\].，示例如下：

[ERROR] HCCL(144905,python):2025-04-20-00:26:54.435.048 [config.cc:413] [145735][InitGroupStage][RanktableCheck]rank[0] device ip family[2] is not same as others[10].

可能原因

两个 rank 获取到的 IP Family 不同，比如一边是 IPv4，而另一边是 IPv6。

解决方法

1. 查询 Device 侧是否配置了 IPv4：

hccn_tool -i {deviceId} -ip -g

2. 查询 Device 侧是否配置了 IPv6：

hccn_tool -i {deviceId} -ip -inet6 -g

3. 确保同一次作业的所有 rank 的 IP Family 保持一致。HCCL 默认先使用 IPv4 协议，若 Device 侧没有配置 IPv4 协议的 IP，则会使用 IPv6 协议对应的 IP。可以使用 HCCL_SOCKET_FAMILY 环境变量指定需要使用的网卡 IP 协议。

注意：日志中 family 打印为枚举值，枚举值与 IP 协议的对应关系如下表：

深度原理：EI0001 的解析与上报机制

结合源码可以更完整地理解 EI0001 的运作机制，这有助于在遇到未覆盖场景时举一反三：

1. 解析入口集中：环境变量解析集中在 alg_env_config.cc 的InitEnvConfig()，按固定顺序解析 HCCL_OP_EXPANSION_MODE、HCCL_DETERMINISTIC、HCCL_INTRA_PCIE_ENABLE / HCCL_INTRA_ROCE_ENABLE、HCCL_ENTRY_LOG_ENABLE、HCCL_USE_NEW_SELECTOR、HCCL_INTER_HCCS_DISABLE、HCCL_OP_RETRY_ENABLE、HCCL_EXEC_TIMEOUT、HCCL_ALG_MULTIPLE_DIMENSION_SPLIT_RATIO、HCCL_ALGO、HCCL_DEBUG_CONFIG、HCCL_DFS_CONFIG 等变量。

2. 设备类型相关解析：部分变量仅在特定设备上解析，例如HCCL_INTER_HCCS_DISABLE、HCCL_OP_RETRY_ENABLE、HCCL_ALGO仅对 A3 设备（DEV_TYPE_910_93）解析，A5 设备走 costmodel 新流程不解析HCCL_ALGO；HCCL_INTRA_PCIE_ENABLE/HCCL_INTRA_ROCE_ENABLE在 A5 设备上不解析不打印。排查时需注意：日志中“未解析”并不代表配置缺失，而是该设备类型不支持。

3. 每条解析都带期望值：每次RPT_ENV_ERR上报都会携带expect字段，例如HCCL_DETERMINISTIC期望true, false or strict、HCCL_EXEC_TIMEOUT期望“最多两位小数的非负数”、HCCL_DEBUG_CONFIG期望ALG,TASK,RESOURCE（可选^前缀）、HCCL_DFS_CONFIG期望inconsistent_check:on/first/off。日志给出的“Expected value”就是这些字符串的展示。

4. 上报与错误返回分离：RPT_ENV_ERR负责向上层错误系统上报（带 key/value 结构），而CHK_PRT_RET负责打印 HCCL 内部 ERROR 日志并返回错误码HCCL_E_PARA（示例日志中errno[1]）。二者配合，既保证外部可见的错误信息完整（变量名 + 值 + 期望），也保证内部调用链可追踪（externalinput.cc→op_base.cc的 call trace）。

5. 调用链追溯：从场景一的日志可见，EI0001 报错发生在InitGroupStage → EnvConfig阶段，最终通过HcclGetRootInfo等对外接口暴露，因此业务侧调用 HCCL 初始化类接口失败时，应优先到 CANN 日志中检索EI0001。

排查速查表

延伸阅读

• 故障诊断总入口：按通信域初始化、参数面建链、任务下发执行等阶段组织的完整错误码排查体系。
• 通信域初始化阶段总体流程：理解 EI0001 在整个初始化流程中的位置。
• 环境变量配置异常（EI0001）入口页：汇总 EI0001 相关全部文档。
• 环境变量参考：全部 HCCL 环境变量的功能、取值范围与配置说明。
• alg_env_config.cc：EI0001 上报点的源码实现。
• adapter_error_manager_pub.h：RPT_ENV_ERR/RPT_INPUT_ERR上报宏定义。

【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl