CANN opbase aclnn返回码全解析：状态码含义、定位方法与源码级排查指南

CANN opbase aclnn返回码全解析状态码含义、定位方法与源码级排查指南【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase导读在基于 CANN opbase 框架库开发或调用 aclnn 算子接口时每个 API 的返回值都是判断调用是否成功的第一手依据。本文以 docs/zh/api/nnopbase/opdev/aclnn_return_code/aclnn_return_code.md 中的返回码清单为骨架结合本仓库 op_errno.h 的宏定义与 composite_op、individual_op 等执行引擎中的真实使用位置系统梳理ACLNN_SUCCESS与ACLNN_ERR_*系列状态码的数值含义、触发场景与排查方向。读完本文你将能够读懂任意 aclnn 接口的返回值快速把报错码映射到根因链路参数校验、shape 推导、tiling、kernel 查找、json 加载等并利用aclGetRecentErrMsg等机制高效定位问题。一、返回码整体架构三段式数值语义从 op_errno.h 的宏定义可以看到aclnn 返回码并非随意编号而是按错误类别分区段组织码段代表错误数值0成功ACLNN_SUCCESS161xxx参数校验类错误ACLNN_ERR_PARAM_NULLPTR161001、ACLNN_ERR_PARAM_INVALID161002361xxx运行时类错误ACLNN_ERR_RUNTIME_ERROR361001561xxx内部异常类错误ACLNN_ERR_INNER561000及 561001~561119 各细分项其中 561 段又分为两个子区间561000~561003对应 API 执行主链路shape 推导、tiling、kernel 查找的异常561101~561119对应 executor 创建与算子信息 json 解析链路的异常。理解这个分段后仅凭返回值即可初步缩小问题范围。异常发生时详细的报错信息可以通过《Runtime 运行时 API》中的aclGetRecentErrMsg接口获取结合报错提示即可进一步排查或联系技术支持。二、常见返回码详解表 1ACLNN_SUCCESS0成功状态码。所有 aclnn 接口正常执行完毕时返回 0表示调用链参数校验、shape 推导、tiling、kernel 启动全部通过。ACLNN_ERR_PARAM_NULLPTR161001参数校验错误入参中存在非法的 nullptr。在 acl_op_api.cpp 中可以看到大量此类校验逻辑例如对 tensor、addr 等指针逐一判空后直接返回ACLNN_ERR_PARAM_NULLPTR。排查时优先检查传入的aclTensor *、workspace 指针、以及可选输出参数是否均已正确初始化。ACLNN_ERR_PARAM_INVALID161002参数校验错误参数值非法。典型场景如两个输入的数据类型不满足输入类型推导关系、tensor 相对索引越界、PCIe 地址刷新失败等见 acl_op_api.cpp 中ACLNN_ERR_PARAM_INVALID的多个返回点。排查时核对 dtype、shape、stride、index 等参数是否符合算子约束。ACLNN_ERR_RUNTIME_ERROR361001API 内部调用 NPU Runtime 接口异常。该错误一般由底层 runtime 层如任务下发、内存操作失败透传而来需结合aclGetRecentErrMsg返回的 runtime 侧错误信息进一步定位常见诱因包括设备状态异常、显存不足、任务队列异常等。三、内部异常码详解表 2内部异常码均由 aclnn API 内部产生按执行阶段细分如下。3.1 API 主链路异常561000 ~ 561003ACLNN_ERR_INNER561000API 发生未细分归类的内部异常兜底状态码。ACLNN_ERR_INNER_INFERSHAPE_ERROR561001API 内部进行输出 shape 推导infershape时发生错误。在 composite_op 引擎中infershape 负责根据输入 shape 推导输出 shape若推导失败即返回该码可检查输入 shape 是否合法、算子是否注册了正确的推导逻辑。ACLNN_ERR_INNER_TILING_ERROR561002API 内部执行 NPU kernel tiling 时发生异常。tiling 是决定算子如何在 NPU 上切分数据与分配核数的关键步骤indv_executor.cpp 中即有找不到 tiling 函数或 tiling 失败时返回该错误码的实现如 MemSet 算子 tiling 函数缺失、kernel json 中找不到对应 tilingKey。ACLNN_ERR_INNER_FIND_KERNEL_ERROR561003API 内部查找 NPU kernel 异常通常意味着算子二进制包kernel 库未安装或未匹配。排查时检查算子包opp 包是否已正确安装以及ASCEND_OPP_PATH指向的路径下是否包含对应算子的 kernel 库。3.2 executor 创建与 json 解析链路异常561101 ~ 561119状态码数值触发场景与排查方向ACLNN_ERR_INNER_CREATE_EXECUTOR561101API 内部创建aclOpExecutor失败可能由操作系统异常导致可检查系统资源内存、句柄数ACLNN_ERR_INNER_NOT_TRANS_EXECUTOR561102API 内部未调用 uniqueExecutor 的ReleaseTo属于执行器生命周期管理异常ACLNN_ERR_INNER_NULLPTR561103API 内部出现 nullptr 异常kernel_tensor.h 中对aclTensor_判空即返回该码ACLNN_ERR_INNER_WRONG_ATTR_INFO_SIZE561104算子的属性个数异常ACLNN_ERR_INNER_KEY_CONFILICT/ACLNN_ERR_INNER_KEY_CONFLICT561105算子的 kernel 匹配 hash key 发生冲突。注意KEY_CONFILICT为拼写错误的历史宏官方已废弃请统一使用KEY_CONFLICT。在 op_kernel.cpp 中kernel 哈希表插入失败即返回该码ACLNN_ERR_INNER_INVALID_IMPL_MODE561106算子的实现模式impl mode参数错误ACLNN_ERR_INNER_OPP_PATH_NOT_FOUND561107未检测到环境变量ASCEND_OPP_PATH。对应实现见 kernel_mgr.cpp 与 kernel_utils.cpp排查时确认环境变量已正确 exportACLNN_ERR_INNER_LOAD_JSON_FAILED561108加载算子 kernel 库中算子信息 json 文件失败kernel_mgr.cpp 中解析 kernel 配置失败即返回该码ACLNN_ERR_INNER_JSON_VALUE_NOT_FOUND561109json 文件中某个字段缺失op_kernel.cpp 中simplifiedKey等字段查找失败即触发ACLNN_ERR_INNER_JSON_FORMAT_INVALID561110json 文件中的 format 字段填写非法值ACLNN_ERR_INNER_JSON_DTYPE_INVALID561111json 文件中的 dtype 字段填写非法值ACLNN_ERR_INNER_OPP_KERNEL_PKG_NOT_FOUND561112未加载到算子的二进制 kernel 库确认算子包安装与ASCEND_OPP_PATH配置ACLNN_ERR_INNER_OP_FILE_INVALID561113加载算子 json 文件字段时发生异常op_kernel.cpp 中对非法 key 值返回该码ACLNN_ERR_INNER_ATTR_NUM_OUT_OF_BOUND561114传入的算子属性个数超过 json 中指定的 attr 个数ACLNN_ERR_INNER_ATTR_LEN_NOT_ENOUGH561115传入的算子属性个数少于 json 中指定的 attr 个数kernel_arg.h 中属性长度不足即返回该码ACLNN_ERR_INNER_INPUT_NUM_IN_JSON_TOO_LARGE561116算子的输入个数超出 32 的上限op_kernel.cpp 中有对应校验ACLNN_ERR_INNER_INPUT_JSON_IS_NULL561117算子信息 json 文件信息描述有缺失ACLNN_ERR_INNER_STATIC_WORKSPACE_INVALID561118解析静态二进制 json 文件中的 workspace 信息时异常ACLNN_ERR_INNER_STATIC_BLOCK_DIM_INVALID561119解析静态二进制 json 文件中的核数block dim使用信息时异常四、源码视角返回码的底层定义与使用约定4.1 宏定义源头所有返回码在 op_errno.h 中统一以#define形式定义与文档表格一一对应。该头文件位于公共头文件目录任何 aclnn 相关模块均可直接引用从源码结构看它是整个 opbase 框架返回码的唯一事实来源。4.2 典型使用模式从 acl_op_api.cpp 和 op_kernel.cpp 可以看出返回码的典型用法是配合CHECK_COND、CHECK_RET、OP_LOGE等宏使用先记录错误日志日志中包含错误码与具体原因再返回对应状态码。这意味着错误码 日志 aclGetRecentErrMsg三者结合才能拿到完整的失败上下文。4.3 数值不可变更的兼容性约定KEY_CONFILICT拼写错误与KEY_CONFLICT共享同一数值 561105历史代码若引用了旧宏仍可编译且语义一致这体现了返回码作为对外 ABI 的稳定性约束——数值一旦发布即不可变更新增错误只能追加新码段。五、实战排查流程先看数值段0 为成功161xxx 直接检查入参361xxx 转向 runtime 层561xxx 深入 API 内部执行链路。再取错误信息调用aclGetRecentErrMsg获取最近一次异常的详细描述多数情况下其中已包含具体的 json 字段名、kernel 路径或 tiling key。分类处理561107/561108/561112 → 检查ASCEND_OPP_PATH环境变量与算子包安装状态561001/561002 → 检查输入 shape 与算子 tiling 配置561108~561117 → 检查算子信息 json 文件的完整性、字段合法性与算子包一致性561105 → 检查算子二进制与 json 的匹配关系确认不存在重复注册的 kernel key。定位到源码本仓库中可在 kernel_mgr.cpp、op_kernel.cpp、kernel_utils.cpp、kernel_arg.h 等文件中找到各错误码的具体触发点作为代码级排查的参考。六、小结aclnn 返回码以成功 0 / 参数 161xxx / 运行时 361xxx / 内部 561xxx的分段设计让开发者仅凭数值即可快速判断错误层级配合aclGetRecentErrMsg的详细信息和 op_errno.h 的宏定义可进一步将每个错误码精确映射到参数校验、shape 推导、tiling、kernel 查找、json 解析等具体执行环节从而在 CANN opbase 框架下实现高效的算子开发与故障排查。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考