跳到主要内容

错误码（darra_error_code）

契约与 darra_ai.h 第 2 节一致。SDK 填进 darra_error_t.hint 的字符串与本文「hint 文案」逐字相同，六种语言绑定原样透传，不得改写。

公开 SDK 是 runtime 构建：可以打开 Studio 已签发的 .darmodel（解密、验票、推理），不含 darra_encrypt_ / darra_issue_ / darra_fingerprint_perturb。密码 / 授权相关错误码描述的是「消费已签发容器」失败，不是公开包能签发。

RKNN 载荷只在 linux-arm64（RK3588 + edge-rknn + librknnrt）运行。Windows / linux-x64 收到 rknn 载荷返回 DARRA_UNSUPPORTED_PAYLOAD；在 Windows 上指名 edge-rknn 返回 DARRA_UNSUPPORTED_PLATFORM。

相关：运行时清单 · 元数据 · C SDK

错误模型（30 秒）​

  • 每个 API 返回 int32_t：0 = 成功，非 0 = 本目录的码。
  • 失败后同一线程立刻调 darra_last_error(&err)：err.message 是什么错、err.hint 怎么修。
  • 错误槽线程局部，下一次 API 调用会清空——取细节要趁热。
  • 参数契约违反（NULL 句柄 / size 未填 / 裸缓冲缺宽高）属调用方 bug，归 DARRA_INTERNAL，message 会指明是哪个参数。

速查表​

码常量一句话责任方
0DARRA_OK成功—
1DARRA_IO_NOT_FOUND文件不存在用户/部署
2DARRA_IO_DENIED文件读写被拒用户环境
3DARRA_BAD_CONTAINER模型容器损坏/非 DARM1部署/输入
4DARRA_BAD_LICENSE授权文件损坏或不配对授权
5DARRA_PASSWORD_REQUIRED该容器要密码但没给调用方
6DARRA_PASSWORD_WRONG密码错用户
7DARRA_MACHINE_MISMATCH绑机授权用错了机器授权
8DARRA_TRIAL_EXHAUSTED试用次数用完授权/商务
9DARRA_UNSUPPORTED_PAYLOAD载荷类型当前环境不支持部署
10DARRA_UNSUPPORTED_PLATFORMOS/架构不在支持矩阵部署
11DARRA_PROVIDER_MISSING运行时 Provider 包未装环境
12DARRA_PROVIDER_ABI_MISMATCHProvider 与内核 ABI 不匹配环境
13DARRA_HARDWARE_MISSING没有所需硬件环境
14DARRA_DRIVER_TOO_OLD驱动版本过低环境（SDK 不代装）
15DARRA_NETWORK_FAILED下载失败网络
16DARRA_CHECKSUM_MISMATCH包完整性校验不过网络/介质
17DARRA_CANCELLED操作被取消中性
18DARRA_INTERNAL内部错误/调用方契约违反SDK 或调用方

逐码详情​

DARRA_OK (0)​

  • 含义：成功。
  • 典型原因：—
  • hint 文案：（空串）
  • 用户下一步：—

DARRA_IO_NOT_FOUND (1)​

  • 含义：路径指向的文件不存在。
  • 典型原因：.darmodel / .darmkey / 图片 / 离线包路径拼错；部署时漏拷文件；进程工作目录变了导致相对路径落空。
  • hint 文案：找不到文件：请核对路径拼写；确认文件随部署包一起拷贝；用相对路径时核对进程工作目录。
  • 用户下一步：核对路径 → 补拷文件 → 重试。

DARRA_IO_DENIED (2)​

  • 含义：文件存在，但读或写被系统拒绝。
  • 典型原因：权限不足；文件被别的进程占用；运行时包装进系统目录但没用管理员身份。
  • hint 文案：文件无法访问：检查读写权限、文件是否被占用；安装运行时包到系统目录请用管理员身份运行。
  • 用户下一步：关占用进程 / 提权 / 换有权限的目录后重试。

DARRA_BAD_CONTAINER (3)​

  • 含义：.darmodel 无法解析——损坏、被截断、被篡改，或根本不是 DARM1 容器。
  • 典型原因：拷贝/下载中断；把明文 .onnx 喂给了 darra_session_open；文件被第三方改动。
  • hint 文案：模型容器无法解析：请从原始介质重新拷贝 .darmodel；明文 ONNX 请改用 darra_session_open_plain。
  • 用户下一步：重取容器文件；确认调的是正确的 open 函数。

DARRA_BAD_LICENSE (4)​

  • 含义：.darmkey 损坏，或与该容器不是同一次签发出的一对（验票位不匹配）。
  • 典型原因：key 文件拷错/截断；模型在 AI Studio 重新加密签发后还在用旧 key。公开 SDK 不能重新签发，须向签发方索取。
  • hint 文案：授权文件无效：确认 .darmkey 与 .darmodel 是同一次签发的一对；不确定就向签发方重新索取授权。
  • 用户下一步：配对核对 → 向签发方重新索取授权。

DARRA_PASSWORD_REQUIRED (5)​

  • 含义：该容器启用了密码通道，调用方没给密码，且没有可用授权文件。
  • 典型原因：darra_session_open 的 password 与 key_path 都传了 NULL。
  • hint 文案：该模型需要密码：请在打开时传入 password，或提供 .darmkey 授权文件。
  • 用户下一步：补密码或授权文件。

DARRA_PASSWORD_WRONG (6)​

  • 含义：密码验票不过。
  • 典型原因：密码拼错（注意大小写/全半角）；用了别的模型的密码。
  • hint 文案：密码不正确：核对大小写后重试；密码无法找回，遗忘请让签发方重新签发（官方不解回明文）。
  • 用户下一步：重试 → 找签发方重签。公开 SDK 不解回明文，也不签发。

DARRA_MACHINE_MISMATCH (7)​

  • 含义：授权绑定了机器指纹，本机指纹不匹配。
  • 典型原因：把授权拷到另一台机器用；换主板/网卡等硬件导致指纹漂移。
  • hint 文案：该授权绑定了另一台机器：请在目标机器上重新签发，或联系签发方变更授权。
  • 用户下一步：联系签发方按新机器重签。

DARRA_TRIAL_EXHAUSTED (8)​

  • 含义：试用计次已用完（TrialRunTicket 归零）。
  • 典型原因：试用模型跑满了签发时的次数。
  • hint 文案：试用次数已用完：请联系签发方购买或签发正式授权。
  • 用户下一步：走商务/签发流程。

DARRA_UNSUPPORTED_PAYLOAD (9)​

  • 含义：容器载荷类型在当前平台/Provider 下不支持。
  • 典型原因：rknn 载荷拿到 Windows 或 linux-x64 上跑（rknn 只在 RK3588 板端 edge-rknn、linux-arm64 运行）；trt-engine 载荷但没有 trt-native Provider；把 .pt / .pth 训练格式当运行时载荷。
  • hint 文案：当前平台或运行时包不支持该载荷类型：用 darra_session_meta_json 确认 payloadKind；rknn 载荷需 RK3588 板端运行时；训练格式请先在 AI Studio 转 ONNX。
  • 用户下一步：核对载荷 × 平台矩阵（见 产品概述），换环境或换载荷。Windows / linux-x64 本机不做 RKNN 转换或推理。

DARRA_UNSUPPORTED_PLATFORM (10)​

  • 含义：整个操作系统/架构不在支持矩阵。
  • 典型原因：macOS（v1 不做）；32 位 Windows；非 x64/ARM64 的 Linux；Windows 上指名 edge-rknn（它是板卡包，永不出现在 Windows 安装列表）。
  • hint 文案：当前系统不在支持矩阵：v1 支持 Windows x64 / Linux x64 / Linux ARM64（RK3588）。
  • 用户下一步：换到支持矩阵内的平台。

DARRA_PROVIDER_MISSING (11)​

  • 含义：需要的运行时 Provider 包未安装。
  • 典型原因：首次使用尚未下载；指名 prefer_provider 但该包没装；现场断网没法在线装。
  • hint 文案：缺少运行时包：调用 darra_runtime_ensure 安装（断网现场用离线整合包），或在 AI Studio 环境管理器下载对应卡片。
  • 用户下一步：darra_runtime_ensure(NULL 或指名 ID, ...) → 重试。见 运行时清单。

DARRA_PROVIDER_ABI_MISMATCH (12)​

  • 含义：Provider 包与 DarraAI.Core 的 ABI 版本不匹配（一新一旧）。
  • 典型原因：只升级了 SDK 没重装 Provider，或反之。
  • hint 文案：运行时包与 SDK 内核版本不匹配：把 Darra.AI SDK 与运行时包升到同一发布批次后重试。
  • 用户下一步：SDK 与 Provider 对齐版本（先升 SDK 再 darra_runtime_ensure 重装包）。

DARRA_HARDWARE_MISSING (13)​

  • 含义：未探测到所选 Provider 需要的硬件。
  • 典型原因：选了 onnx-cuda / onnx-trt-ep 但机器没有 N 卡；onnx-openvino 但非 Intel 平台；edge-rknn 但板子 NPU 未就绪。
  • hint 文案：未探测到所需硬件：用 darra_diag_collect 确认硬件识别结果；无对应硬件请改用 onnx-cpu。
  • 用户下一步：diag 核对 → 换匹配的 Provider 或装硬件。指名 Provider 不可用时 fail-closed，不会静默落到别的 Provider。

DARRA_DRIVER_TOO_OLD (14)​

  • 含义：硬件在，但驱动版本低于 Provider 包要求（如 NVIDIA 驱动低于包声明的 minDriverCuda；RK3588 板镜像缺 NPU 驱动）。
  • 典型原因：驱动多年未升；板厂镜像太旧。
  • hint 文案：驱动版本过低：请按诊断 JSON 给出的确切版本要求到官方站点升级驱动；SDK 不自动安装或升级系统驱动。
  • 用户下一步：升驱动（要管理员/重启）→ 重试；升不了就退回 onnx-cpu。

DARRA_NETWORK_FAILED (15)​

  • 含义：运行时清单或 Provider 包下载失败。
  • 典型原因：到 download.darra.xyz 的连通性断了；代理/防火墙拦截；DNS 污染。
  • hint 文案：网络下载失败：检查到 download.darra.xyz 的连通性与代理设置；断网现场改用离线整合包（darra_runtime_ensure 的 offline 参数）。
  • 用户下一步：修网络重试，或走离线包。见 发布与下载。

DARRA_CHECKSUM_MISMATCH (16)​

  • 含义：下载包或离线包的 sha256 校验不过——包被损坏或篡改。
  • 典型原因：下载中断产生残包；离线包拷贝介质（U 盘）有坏块；中间人被换包。这是安全门，fail-closed 绝不放行。
  • hint 文案：包完整性校验失败：删除残包重新下载；离线包请从原始介质重新拷贝。校验失败不会被跳过，这是安全保护。
  • 用户下一步：重取包 → 重试；反复失败换网络/介质。

DARRA_CANCELLED (17)​

  • 含义：操作被取消。v1 唯一来源：另一个线程调了 darra_runtime_ensure_cancel，在飞的 darra_runtime_ensure 随之取消。
  • 典型原因：用户在环境管理器/安装界面点了「取消」。
  • hint 文案：操作已取消：半成品已清理，需要时重新调用即可。
  • 用户下一步：需要就重调；不需要就当无事发生。

DARRA_INTERNAL (18)​

  • 含义：两类——① 调用方参数契约违反（message 会指明是哪个参数：NULL 句柄 / NULL 出参 / size 字段未填 / 裸缓冲缺宽高 / len 不足）；② SDK 自身的内部错误。
  • 典型原因：① 绑定层 bug 或调用顺序错；② SDK 缺陷。
  • hint 文案：内部错误：若描述中指明某参数违反契约，请按 api-c.md 修正调用；否则用 darra_diag_collect 导出诊断并联系支持。
  • 用户下一步：先看 message 是不是自己调错（见 C SDK）；排除后打包 diag JSON 报障。诊断 JSON 不含密钥 / 密码 / token / 机器指纹字节。

hint 文案纪律​

  1. hint 面向最终用户：说「怎么办」，不说「为什么失败」（那是 message 的职责）。
  2. 禁止出现密钥 / 密码 / token / 机器指纹字节；禁止暗示「可以跳过校验 / 降级绕过」。
  3. 驱动 / 系统级问题必须给官方链接或明确动作，且重申「SDK 不代装」。
  4. 公开 runtime 包物理上没有加密 / 签发符号；hint 不得暗示客户能用公开 SDK 重新加密或签发。