故障定位与解决指南)
CANN HCCL 环境变量配置异常EI0001故障定位与解决指南【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hcclHCCLHuawei Collective Communication Library在通信域初始化阶段会解析大量环境变量当其中任一变量取值不合法时会在日志中打印EI0001Config_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_guardstd::mutex lock(g_algEnvConfigMutex); // 解析算子展开模式 HcclResult ret ParseOpExpansion(); RPT_ENV_ERR( ret ! HCCL_SUCCESS, EI0001, std::vectorstd::string({value, env, expect}), std::vectorstd::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定位思路在业务日志中搜索故障码查找关键字EI0001。读取错误详情一般情况下日志的 ERROR MESSAGE 和 CANN 日志中会显示配置异常的环境变量名称错误原因合理的配置范围。按建议调整依据日志打印的建议调整环境变量取值。仍有疑问时查阅环境变量参考参照 环境变量参考该文档按功能、性能、网络、调试、可靠性、安全等维度分类收录了全部 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的系统抽象层SALSystem 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。解决方法查询 Device 侧是否配置了 IPv4hccn_tool -i {deviceId} -ip -g查询 Device 侧是否配置了 IPv6hccn_tool -i {deviceId} -ip -inet6 -g确保同一次作业的所有 rank 的 IP Family 保持一致。HCCL 默认先使用 IPv4 协议若 Device 侧没有配置 IPv4 协议的 IP则会使用 IPv6 协议对应的 IP。可以使用 HCCL_SOCKET_FAMILY 环境变量指定需要使用的网卡 IP 协议。注意日志中 family 打印为枚举值枚举值与 IP 协议的对应关系如下表IP Family 枚举值IP 协议2IPv410IPv6深度原理EI0001 的解析与上报机制结合源码可以更完整地理解 EI0001 的运作机制这有助于在遇到未覆盖场景时举一反三解析入口集中环境变量解析集中在 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 等变量。设备类型相关解析部分变量仅在特定设备上解析例如HCCL_INTER_HCCS_DISABLE、HCCL_OP_RETRY_ENABLE、HCCL_ALGO仅对 A3 设备DEV_TYPE_910_93解析A5 设备走 costmodel 新流程不解析HCCL_ALGOHCCL_INTRA_PCIE_ENABLE/HCCL_INTRA_ROCE_ENABLE在 A5 设备上不解析不打印。排查时需注意日志中“未解析”并不代表配置缺失而是该设备类型不支持。每条解析都带期望值每次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”就是这些字符串的展示。上报与错误返回分离RPT_ENV_ERR负责向上层错误系统上报带 key/value 结构而CHK_PRT_RET负责打印 HCCL 内部 ERROR 日志并返回错误码HCCL_E_PARA示例日志中errno[1]。二者配合既保证外部可见的错误信息完整变量名 值 期望也保证内部调用链可追踪externalinput.cc→op_base.cc的 call trace。调用链追溯从场景一的日志可见EI0001 报错发生在InitGroupStage → EnvConfig阶段最终通过HcclGetRootInfo等对外接口暴露因此业务侧调用 HCCL 初始化类接口失败时应优先到 CANN 日志中检索EI0001。排查速查表场景日志关键字根因解决动作通用 EI0001EI0001、Value *** for environment variable *** is invalid环境变量取值不合法按日志建议范围调整参照 环境变量参考HCCL_RDMA_SL 配置错误HCCL_RDMA_SL[1000] is invalid. except: [0, 7]取值越界调整到合法范围如 0~7详见 HCCL_RDMA_SLHCCL_SOCKET_IFNAME 配置错误get host ip fail by socket Ifname指定网卡在当前环境或容器内不存在改为环境上真实存在的网卡名详见 HCCL_SOCKET_IFNAMEIP Family 校验不一致device ip family[2] is not same as others[10]各 rank 的 IP 协议族不一致用hccn_tool检查 IP必要时用 HCCL_SOCKET_FAMILY 统一协议延伸阅读故障诊断总入口按通信域初始化、参数面建链、任务下发执行等阶段组织的完整错误码排查体系。通信域初始化阶段总体流程理解 EI0001 在整个初始化流程中的位置。环境变量配置异常EI0001入口页汇总 EI0001 相关全部文档。环境变量参考全部 HCCL 环境变量的功能、取值范围与配置说明。alg_env_config.ccEI0001 上报点的源码实现。adapter_error_manager_pub.hRPT_ENV_ERR/RPT_INPUT_ERR上报宏定义。【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考