CANN Runtime 数据 Dump 错误码(EP0001~EP0008)全解析:从报错格式到源码级排查
CANN Runtime 数据 Dump 错误码(EP0001~EP0008)全解析:从报错格式到源码级排查
导读
Dump(数据采集)是 CANN Runtime 维测体系中的核心能力,用于在算子执行、模型推理过程中按需采集输入输出张量、算子统计信息与异常现场。当 Dump 配置校验、文件解析或接口调用出现问题时,Runtime 会通过 EP0001~EP0008 这一组错误码精准上报原因。本文以本仓库 docs/zh/error_code_ref/Dump-Errors 下的错误码文档为主体,结合 src/dfx/adump 模块的源码实现,完整梳理这 8 个错误码的报错格式、占位符语义、典型触发场景与解决步骤,帮助你快速定位 Dump 配置问题并恢复任务运行。
一、错误码全景总览
EP 系列错误码(EP 即 Error of Dump/Error of Parse 系列)由 Runtime 的 adump(Ascend Dump)组件在配置解析阶段和接口参数校验阶段产生。按照错误性质,可以划分为三大类:
| 错误码 | 名称 | 所属类别 | 一句话描述 |
|---|---|---|---|
| EP0001 | Config_Error | 配置项错误 | 配置文件中缺少某个配置项 |
| EP0002 | Config_Error | 配置项错误 | 配置项取值不在合法枚举范围内 |
| EP0003 | Config_Error | 配置项错误 | 配置项取值本身不合法(如路径无权限) |
| EP0004 | File_Operation_Error_Parse | 文件解析错误 | 配置文件无法被正确解析(JSON 语法问题) |
| EP0005 | Config_Error | 配置项错误 | 多个配置项之间存在互斥冲突 |
| EP0006 | Invalid_Argument | 接口参数错误 | 接口参数值不合法(如路径无法创建) |
| EP0007 | Invalid_Argument_Null_Pointer | 接口参数错误 | 接口参数为空指针 |
| EP0008 | Invalid_Argument_API_Call_Sequence | 接口调用顺序错误 | 接口调用顺序不满足前置条件 |
在源码中,这 8 个错误码的字段定义与上报宏统一维护在 adump_error_manager.h 中,每个宏在打印 IDE 日志的同时,通过 REPORT_PREDEFINED_ERR_MSG 将结构化字段(如 item、path、value、reason 等)注册进错误码体系,供上层解析与定位。
二、配置项类错误:EP0001 / EP0002 / EP0003 / EP0005
配置项类错误是 Dump 使用中最常见的一类,均产生于 acl.json 配置文件的解析与校验流程。源码 dump_config_converter.cpp 中的 DumpConfigConverter 负责将 acl.json 中的 Dump 段转换为内部配置结构,并在转换过程中逐一校验各配置项。
2.1 EP0001:配置项缺失
报错格式(占位符 %s 依次为配置项、配置文件、报错原因):
The content of configuration item %s in configuration file %s is invalid. Reason: %s.
报错示例:
The content of configuration item dump_path in configuration file acl.json is invalid. Reason: The configuration item is not found.
触发场景:acl.json 中声明了 Dump 配置段,但未包含必需的配置项(如上例中的 dump_path)。从源码看,from_json 对 dump_path 采用 GetStringIfExist 的读取方式,若该键缺失,后续校验阶段就会以 EP0001 的形式上报。
解决方法:按照 Reason 中的提示,在 acl.json 对应配置段中补齐缺失的配置项。
2.2 EP0002:配置项取值不在枚举范围内
报错格式(占位符 %s 依次为取值、配置项、文件名、期望值):
Value %s for configuration item %s in configuration file %s is invalid. Expected value: %s.
报错示例:
Value abc for configuration item dump_op_switch in configuration file acl.json is invalid. Expected value: on/off.
触发场景:配置项的取值非法。以上例中的 dump_op_switch 为例,源码 dumpValidOptions 表中将其合法取值限定为 on/off(即 ADUMP_DUMP_STATUS_SWITCH_ON / ADUMP_DUMP_STATUS_SWITCH_OFF),填写 abc 必然触发该校验。
解决方法:按照报错提示中的 Expected value 修改配置项取值。
2.3 EP0003:配置项取值本身不合法
报错格式(占位符 %s 依次为取值、配置项、文件名、报错原因):
Value %s for configuration item %s in configuration file %s is invalid. Reason: %s.
报错示例:
Value /npu/abc for configuration item dump_path in configuration file acl.json is invalid. Reason: The value is a path without read and write permissions.
触发场景:配置项取值虽然类型正确,但内容不满足要求。典型如 dump_path 指向的目录不存在、或当前进程对该路径无读写权限。从源码结构看,adump 在配置校验阶段会调用底层文件工具检查路径的创建能力与权限(参见 file_utils.cpp)。
解决方法:按照 Reason 中的提示检查并修改配置——通常需要确保 Dump 目录存在且具有读写权限。
2.4 EP0005:配置项冲突
报错格式(占位符 %s 依次为文件名、报错原因):
Conflict of configuration items in configuration file %s. Reason: %s.
报错示例:
Conflict of configuration items in configuration file /home/acl.json. Reason: Configuration items dump_scene and dump_stats cannot be both configured.
触发场景:多个配置项之间存在互斥关系。源码中为此准备了一组专门的宏(REPORT_EP0005_ITEM_CANNOT_SET_WHEN_ITEM_SET、REPORT_EP0005_ITEM_CANNOT_SET_WHEN_ITEM_VALUE、REPORT_EP0005_ITEM_VALUE_CANNOT_SET_WHEN_ITEM_VALUE 等),覆盖“某配置项存在时另一配置项不可配置”“某配置项为特定值时另一配置项不可配置”等组合冲突场景。
解决方法:按照 Reason 中提示的冲突双方,删除或修改其中一个配置项。
2.5 配置项合法取值速查表
为避免反复触发 EP0001~EP0003/EP0005,这里给出 dump_config_converter.cpp 中 dumpValidOptions 表确认的 Dump 配置项及其合法取值(当前仓库实现,实际取值以版本配套文档为准):
| 配置项 | 合法取值 | 默认值(源码 from_json) |
|---|---|---|
dump_path |
任意字符串路径(需可创建且有读写权限) | 无(缺失即报 EP0001) |
dump_mode |
input / output / all |
output |
dump_op_switch |
on / off |
off |
dump_debug |
on / off |
off |
dump_scene |
lite_exception / aic_error_brief / aic_error_norm / aic_error_detail / watcher |
无 |
dump_data |
tensor / stats |
无 |
dump_kernel_data |
all / printf / tensor / assert / timestamp |
all |
dump_level |
op / kernel / all |
all |
dump_stats |
max / min / avg / nan / neg_inf / pos_inf / l2norm(数组形式) |
无 |
dump_step |
字符串 | 无 |
其中 dump_scene 的 aic_error_brief / aic_error_norm / aic_error_detail 三种取值在源码中还同时被登记为环境变量场景(envDumpScenes),用于支持通过环境变量触发异常场景 Dump。需要注意的是,dump_scene 与 dump_stats 同时配置会触发 EP0005 冲突(如错误示例所示)。
三、文件解析类错误:EP0004
3.1 报错格式与示例
报错格式(占位符 %s 依次为文件名、报错原因):
Failed to parse file %s. Reason: %s.
报错示例:
Failed to parse file /home/test_dump/acl.json. Reason: [json.exception.type_error.302] type must be array, but is string.
触发场景:acl.json 本身无法被解析器解析。示例中原因字段来自底层 JSON 解析库(nlohmann/json)的异常描述,表明某个配置段期望是数组(如 dump_stats、layer、opname_range 等),实际却写成了字符串。从源码看,adump 使用 nlohmann::json 解析配置文件,并在解析失败时通过 REPORT_EP0004_PARSE_ERROR 宏上报,同时打印包含模块名的 IDE 日志。
解决方法:按照 Reason 中给出的解析器异常信息定位具体的语法或类型错误并修正配置文件。常见的可检查项包括:
- 引号、逗号、括号是否配对完整;
- 某个字段期望为数组(
[])却写成了字符串(""); - 字段名是否使用了合法的 JSON 键格式;
- 是否存在注释或尾逗号等非标准 JSON 内容。
四、接口参数类错误:EP0006 / EP0007 / EP0008
除配置文件外,adump 还提供一组面向开发者的 C/C++ 接口(如 aclopStartDumpArgs、acldumpRegCallback、aclmdlInitDump 等),这些接口在参数校验与调用顺序检查失败时会产生下述错误码。
4.1 EP0006:接口参数值非法
报错格式(占位符 %s 依次为接口名、参数名、报错原因):
%s failed. Value %s for parameter %s is invalid. Reason: %s.
报错示例:
aclopStartDumpArgs failed. Value /output for parameter path is invalid. Reason: The parameter is a path and the path fails to be created. Error: No such file or directory.
触发场景:接口参数的值不满足要求。示例中 aclopStartDumpArgs 的 path 参数指向的目录无法创建,报错原因中直接透传了底层文件系统错误(No such file or directory)。
解决方法:按照 Reason 中的提示修正参数值。例如确保路径的父目录存在、路径合法且具备创建目录的权限。
4.2 EP0007:参数为空指针
报错格式(占位符 %s 依次为接口名、参数名):
%s failed because %s cannot be a NULL pointer.
报错示例:
acldumpRegCallback failed because messageCallback cannot be a NULL pointer.
触发场景:向接口传入了 NULL 指针参数。示例中 acldumpRegCallback 要求传入回调函数指针 messageCallback,该参数不能为空。
解决方法:在调用前检查相关指针变量,确保传入有效的非空指针;对于回调注册类接口,需先完成回调对象的初始化。
4.3 EP0008:接口调用顺序错误
报错格式(占位符 %s 依次为接口名、报错原因):
%s failed. Reason: %s.
报错示例:
aclmdlInitDump failed. Reason: aclInit must be executed before aclmdlInitDump is called.
触发场景:接口调用未满足前置条件。示例中 aclmdlInitDump 依赖运行时上下文已经初始化,必须在 aclInit 成功之后再调用。
解决方法:按照 Reason 中的提示调整调用顺序,补齐前置初始化步骤(如 aclInit、aclrtSetDevice 等)。
五、源码级原理:错误码如何产生与上报
理解错误码的产生链路有助于快速排查。以配置文件校验为例,整体流程如下:
- 读取:Runtime 读取
acl.json,定位 Dump 配置段; - 反序列化:dump_config_converter.cpp 中的
from_json将 JSON 各字段映射为内部结构体RawDumpConfig(dumpPath、dumpMode、dumpOpSwitch、dumpScene、dumpStats等); - 字段类型检查:
CheckDumpFieldTypes对dump_path、dump_mode、dump_op_switch、dump_level、dump_scene、dump_data、dump_debug、dump_kernel_data、dump_step等字符串字段做类型校验; - 取值校验:对照
dumpValidOptions表逐一比对枚举取值,非法即触发 EP0002; - 冲突校验:检查互斥配置组合,冲突即触发 EP0005;
- 解析失败兜底:任何一步因 JSON 语法或结构问题无法继续时,触发 EP0004。
每一步对应的上报宏都集中在 adump_error_manager.h:
REPORT_EP0001_ITEM_ERROR:配置项缺失,字段item/path/reason;REPORT_EP0002_ENUM_VALUE_INVALID:枚举取值非法,字段value/item/path/expected_value;REPORT_EP0003_INVALID_VALUE:取值不合法,字段value/item/path/reason;REPORT_EP0004_PARSE_ERROR:解析失败,字段path/reason;REPORT_EP0005_*系列:配置冲突,字段path/reason;- EP0006 / EP0007 / EP0008 对应接口层校验宏,分别携带接口名、参数名与原因。
从宏实现可以看到,每个错误码上报时都会同时做两件事:一是输出 IDE 日志(IDE_LOGE,带模块名前缀,便于在日志文件中直接检索);二是将结构化字段注入错误码注册体系(REPORT_PREDEFINED_ERR_MSG),供 Runtime 错误码框架统一收集与呈现。
六、端到端排查实践建议
当看到 EP0001~EP0008 报错时,推荐按以下步骤快速定位:
- 记录完整报错信息:保留错误码、
Reason字段及日志中同一时间戳附近的[adump]模块日志,Reason往往已经指向根因; - 检查配置文件:对于配置类错误(EP0001/0002/0003/0005),对照上文《配置项合法取值速查表》逐项核对
acl.json中的 Dump 配置段; - 验证 JSON 合法性:对于 EP0004,用 JSON 校验工具确认文件可被标准解析器解析,并核对数组/字符串类型是否与预期一致;
- 核对接口调用代码:对于接口类错误(EP0006/0007/0008),检查参数值、指针有效性以及接口调用顺序,确保
aclInit等前置初始化已完成; - 查阅配套文档:Dump 配置的完整参数说明可参考 18_dump_configuration.md;Dump 功能整体介绍见 Runtime 维测文档目录。
七、参考
- 错误码索引:docs/zh/error_code_ref/Dump-Errors/DUMP-Errors.md
- EP0001:EP0001-Config_Error.md
- EP0002:EP0002-Config_Error.md
- EP0003:EP0003-Config_Error.md
- EP0004:EP0004-File_Operation_Error_Parse.md
- EP0005:EP0005-Config_Error.md
- EP0006:EP0006-Invalid_Argument.md
- EP0007:EP0007-Invalid_Argument_Null_Pointer.md
- EP0008:EP0008-Invalid_Argument_API_Call_Sequence.md
- 错误码上报宏实现:src/dfx/adump/adump/common/adump_error_manager.h
- 配置解析与取值校验实现:src/dfx/adump/adump/impl/dump_config_converter.cpp