企业官网建设流程全解析

CANN opbase 错误码 EZ0002 解析：Invalid_Attr 属性值非法错误的上报、定位与排查

【免费下载链接】opbase本项目是CANN算子库的基础框架库，为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase

导读

本文围绕 CANN/opbase 开源仓库中算子错误码体系中的EZ0002（Invalid_Attr）展开，说明该错误码所对应的报错格式、占位符语义与典型报错样例，并结合仓库源码深入讲解其底层上报机制（OP_LOGE_WITH_INVALID_ATTR宏与REPORT_PREDEFINED_ERR_MSG错误码注册机制），给出算子在实现与调测阶段触发 EZ0002 的完整排查思路，帮助算子开发者快速定位属性值非法问题，并与 EZ0001、EZ0003、EZ0024 等相邻错误码正确区分使用。

EZ0002 是什么

EZ0002 是 CANN/opbase 错误码体系中归属于Operator Errors（算子错误）类别的预定义错误码，错误标题为Invalid_Attr，用于表达"算子的属性（Attribute）值非法"这一错误场景。在 CANN 算子开发流程中，算子通常通过 aclnn 接口或算子实现对外暴露，其行为由若干属性（Attribute）控制（例如dim、axis、update_type等）。当调用方传入的属性值不在算子定义所允许的取值范围内时，算子实现会通过日志与错误码上报机制抛出 EZ0002，提示使用者属性取值有误。

该错误码在仓库的错误码注册表中定义于 src/op_common/log/log.cpp，其注册元数据如下：

在枚举层面，错误码还与内部视图错误码INVALID_ATTR_VALUE（数值 35001）对应，见 include/op_common/log/error_code.h，该枚举属于Ops::Base::ViewErrorCode，是错误码在上报链路中与日志/DFX 视图关联的内部编码。

错误信息格式与占位符语义

EZ0002 的报错格式如下：

Attribute %s of %s has incorrect value %s. It should be %s.

其中四个占位符%s依次填充：

报错示例

仓库给出的标准报错示例如下：

Attribute dim of KthValue has incorrect value 5. It should be [-3, 2].

该示例的语义是：KthValue算子的dim属性被传入了非法值5，而算子允许的取值范围是[-3, 2]。读者可以据此快速定位是哪条语句、哪个算子、哪个属性出了问题，并依据"正确值"提示直接修正调用侧传入的属性值。

EZ0002 的源码级上报机制

1. 错误码注册表

EZ0002 的完整错误描述（错误类、标题、消息模板、参数列表、官方建议）统一注册在错误码元数据表中，见 src/op_common/log/log.cpp。该注册表同时定义了 EZ0001（Invalid_Input_Shape）、EZ0003（Invalid_Attr_Size）等相邻错误码，上报时按错误码 ID 查询并填充Arglist中声明的字段，从而生成结构化的错误信息。从源码结构看，该注册表是算子错误码统一出口，其他 EZ 系列错误码均以同样的 JSON 元数据结构注册于此。

2. 上报宏 OP_LOGE_WITH_INVALID_ATTR

在算子或 aclnn 实现中，EZ0002 由宏OP_LOGE_WITH_INVALID_ATTR触发，其定义位于 include/op_common/log/log.h。该宏的调用方式为：

OP_LOGE_WITH_INVALID_ATTR(entityName, attrName, incorrectVal, correctVal)

宏体内部做了两件事：

1. 通过OP_LOGE_LIBOPAPI_REPORT输出 ERROR 级别日志，日志模板即 EZ0002 的消息格式"Attribute %s of %s has incorrect value %s. It should be %s."，并携带文件、行号、子模块名（OPS_BASE）、函数名、线程号等上下文信息（见 include/op_common/log/log.h）；
2. 通过REPORT_PREDEFINED_ERR_MSG("EZ0002", msgKey, msgvalue)上报预定义错误码，其中 msgKey 依次为attr_name、op_name、incorrect_val、correct_val，与错误码注册表中的Arglist严格对应。

REPORT_PREDEFINED_ERR_MSG的上报动作使错误信息能够在 DFX（故障诊断）体系中登记，便于上层工具与调用方按错误码检索、归类问题。

3. 接口文档与调用示例

仓库为该宏提供了独立接口文档 docs/zh/api/op_common/log/OP_LOGE_WITH_INVALID_ATTR.md，其参数说明如下：

文档给出的调用示例（预期输出：Attribute axis of MyOp has incorrect value 3. It should be 0 or 1.）：

if (axis_ != "0" && axis_ != "1") { OP_LOGE_WITH_INVALID_ATTR("MyOp", "axis", std::to_string(axis_), "0 or 1"); return false; }

值得注意的是，接口文档标注该宏已废弃，建议使用 OP_LOGE_FOR_INVALID_VALUE（对应 EZ0024 错误码）替代。因此在新建代码中，属性/参数值校验类错误应优先选用OP_LOGE_FOR_INVALID_VALUE；但对于存量算子仍会通过 EZ0002 报错，理解其语义对排查历史日志仍然必要。

触发 EZ0002 后的排查方法

根据错误码注册表中给出的官方建议（Solution: Check whether the operator attribute is correct），排查步骤归纳如下：

1. 定位报错主体：从报错文本的第 2 个占位符确认是哪个算子或 aclnn 接口报错，例如示例中的KthValue；
2. 确认非法属性：从第 1 个占位符确认属性名（如dim），第 3 个占位符给出的是实际传入的错误值（如5）；
3. 对照正确取值范围：第 4 个占位符直接给出了算子允许的正确值或取值范围（如[-3, 2]），将其与实际值对比即可判断非法原因——通常为调用侧传参越界、类型转换丢失精度或使用了算子不支持的特殊值；
4. 修正调用参数：检查生成算子的上层代码（构图/建图侧），确保属性值落在允许范围内后重新执行。

当报错同时伴随日志出现时，日志会携带出错的文件、行号与线程号，可结合 include/op_common/log/log.h 中OP_LOGE_LIBOPAPI_REPORT的输出格式，在源码中进一步回溯到校验逻辑所在位置。

与相邻错误码的区分

EZ0002 属于算子错误族中的"属性校验"分支，与几个相邻错误码在语义上易混淆，仓库错误码注册表（src/op_common/log/log.cpp）与总览文档 docs/zh/error_code/Operator-Errors/Operator-Errors.md 给出了完整清单，常见区分如下：

判别要点：EZ0002 特指"属性值"（Attribute Value）错误，EZ0003 特指"属性大小/长度"（Attribute Size）错误，EZ0024 则泛指算子或接口的"参数值"错误。报错文本中出现Attribute ... has incorrect value即为 EZ0002，出现Parameter ... has incorrect value则为 EZ0024。英文版同主题文档见 docs/en/error_code/Operator-Errors/EZ0002-Invalid_Attr.md。

小结

EZ0002（Invalid_Attr）是 CANN/opbase 错误码体系中面向"算子属性值非法"场景的标准错误码，其消息模板Attribute %s of %s has incorrect value %s. It should be %s.通过四个占位符完整承载了属性名、算子名、错误值与正确值四类信息，配合错误码注册表与OP_LOGE_WITH_INVALID_ATTR宏的底层实现，形成"日志 + 错误码上报"双通道的 DFX 能力。开发者在调测中只需依据报错文本中的正确值提示即可快速修正属性传参；在算子实现中，则应遵循仓库接口文档的建议，优先使用 OP_LOGE_FOR_INVALID_VALUE（EZ0024）进行新的参数校验上报。

【免费下载链接】opbase本项目是CANN算子库的基础框架库，为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase