---
title: 快速定位定界思路
description: "1. 确认是否为HCCL相关的异常报错。"
url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/API/hcclug/hcclug_000025.html
sourcePath: /source/zh/canncommercial/900/API/hcclug/hcclug_000025.html
indexId: d50f9e1120b20128e1f6a972b9022b7f8e32188a2641abde3810c7de4fc471c759
---
# 快速定位定界思路

1. 确认是否为HCCL相关的异常报错。

  - HCCL针对常见的报错场景，会在业务打印日志中上报错误信息及故障信息，若在业务日志中存在"EI****"或"EJ****"的故障码，则可根据对应的故障信息排查故障，或结合CANN日志中的报错信息对相关章节进行排查，故障码列表可见    HCCL相关故障码
。
  - 除了打印的故障码信息，HCCL在CANN日志中会打印HCCL组件的ERROR级别日志，因此若在CANN日志中没有发现HCCL组件的报错日志，需排查是否有其他组件的报错信息，若无报错，请注意训练脚本本身有无异常、是否存在core dump或进程卡住等其他异常
2. 收集全量CANN日志。
  由于HCCL集合通信是一个通信域下全局的协同行为，某个节点上有HCCL的异常报错往往是因为在等待某个对端超时，此时需要结合对端的日志信息一起排查问题的根因。对于HCCL问题的定位定界需要收集集群下所有节点的CANN日志，包括debug目录和run目录的日志。

3. 确认当前报错阶段，并根据不同阶段进行排查。
HCCL业务存在三个阶段，分别是通信域初始化、参数面建链和通信算子执行，由于不同阶段使用的硬件资源、通信拓扑和同步方式有明显差异，因此可先确认当前HCCL报错所在的阶段，再根据不同的阶段找到对应的章节做进一步排查。

  - HCCL在常见的报错场景增加了多级检索关键字，可以根据报错日志中的关键字快速识别当前报错阶段，并根据报错信息做进一步排查和定位。多级检索关键字详见    HCCL多级检索关键字
，如下日志表明在算子执行阶段发生了超时报错，且当前的算子展开方式为HOST模式：

```
[ERROR] HCCL(858209,all_reduce_test):2025-12-10-19:52:32.589.097 [task_exception_handler.cc:27] [858274]
[TaskExecStage][Timeout][HOST]
Task run failed, base information is streamID:[1740], taskID[23], tag[AllReduce_127.0.0.1%enp_60000_0_1765367469951573], AlgType(level 0-1-2):[fullmesh-ring-NHR].
```


    注意：多级检索关键字功能仅在CANN 8.5.0版本及后续版本支持，对于不支持的版本或没有检索到关键字的场景，可根据其他方法判断当前的报错阶段。

  - HCCL提供了通信域创建接口和通信算子接口，且接口均为同步下发，异步执行。因此可分为以下几个场景：

    - 若业务在调用通信域创建接口失败时，或在报错日志中有"topoinfo"、"ranktable"关键字打印，可参考      通信域初始化阶段
章节进一步排查。
    - 若业务在调用通信算子接口失败时，或在报错日志中有"transport"关键字打印，可参考      参数面建链阶段
章节进一步排查。
    - 若业务创建通信域接口和通信算子下发均成功，而是在触发流同步时有HCCL的算子执行失败，或在报错日志中有"TaskExceptionHandler"、"FFTS+ run failed"、"Task run failed"关键字打印，可参考      任务下发执行阶段
章节做进一步排查。
      除此三个阶段的关键信息外，若在业务的打印日志中有明确的错误码信息，如"EI0001"，可直接根据错误码在后续内容中找到对应的故障码，并进一步排查。


#### HCCL多级检索关键字


**表1 HCCL多级检索关键字**

| 一级关键字 | 二级检索关键字 | 故障场景 |
| --- | --- | --- |
| InitGroupStage | EnvConfig | 通信域初始化阶段环境变量配置异常 |
| InitGroupStage | RanktableConfig | 通信域初始化阶段rankTable文件读取失败 |
| InitGroupStage | RanktableCheck | 通信域初始化阶段rankTable集群信息校验失败 |
| InitGroupStage | RanktableDetect | 通信域初始化阶段集群信息探测失败 |
| InitGroupStage | Resource | 通信域初始化节点资源初始化失败 |
| InitChannelStage | ParameterConflict | 参数面建链阶段参数一致性校验失败 |
| InitChannelStage | VersionConflict | 参数面建链阶段HCCL版本不一致校验失败 |
| InitChannelStage | Timeout | 参数面建链阶段超时报错 |
| TaskExecStage | InvalidArgument | 算子执行阶段入参校验失败 |
| TaskExecStage | Not Supported | 算子执行阶段不支持场景 |
| TaskExecStage | Timeout | 算子执行阶段执行超时 |
| TaskExecStage | RunFailed | 算子执行阶段执行失败 |
| TaskExecStage | HeartbeatAbnormal | 算子执行阶段发现心跳异常事件 |


#### HCCL相关故障码


**表2 HCCL相关故障码信息**

| 故障码 | 故障码说明 |
| --- | --- |
| EI0001 | 环境变量配置异常 |
| EI0002 | 通信算子执行超时 |
| EI0003 | 集合通信算子入参校验失败 |
| EI0004 | rankTable文件加载失败 |
| EI0005 | 参数一致性校验失败 |
| EI0006 | 通信算子参数面建链超时 |
| EI0007 | 资源初始化失败 |
| EI0008 | HCCL版本不一致，校验失败 |
| EI0011 | QP内存资源申请失败 |
| EI0012 | 算子执行时发生SDMA任务异常 |
| EI0013 | 算子执行时发生ROCE CQE ERROR异常 |
| EI0014 | 集群信息校验失败 |
| EI0015 | 通信域集群信息协商阶段超时 |
| EI0019 | 通信域创建阶段server节点端口绑定失败或参数面建链阶段端口绑定失败 |