错误处理

失败时 JNI 调 darra_last_error，再 AiException.throwByCode。hint 原文透传，不改写。getCode() / getMessage() / getHint() 分别对应 C 的 code / message / hint。未知码抛基类，不丢信息。code == 0 为 no-op。

公开 SDK 是 runtime 构建：密码 / 授权相关错误码描述的是「消费已签发容器」失败，不是公开包能签发。

逐码含义与 hint 文案见 错误码目录。

错误类型

类型	来源	处理方式
AiException 子类	每个 darra_error_code（除 OK）	catch 对应嵌套子类；getHint() 原样展示给最终用户
未知新码	未来 Core 追加的码	抛基类 AiException，getCode() 原样保留
参数契约违反	空路径 / 空 imageBytes / 空 desc / 裸缓冲宽高 ≤ 0 / 会话已关闭	AiException.InternalException，message 指明哪个参数
加载 / ABI	natives 缺失或 major ≠ 1	UnsatisfiedLinkError / UnsupportedPlatformException，禁止继续调用

捕获

try {
    try (AiSession s = AiSession.open("model.darmodel", "model.darmkey", null, null)) {
        String json = s.inferImage(image, ImageDesc.auto());
    }
} catch (AiException.CancelledException ex) {
    // 半成品已清理，需要时重新 ensure / open 即可
} catch (AiException ex) {
    System.err.println("[" + ex.getCode() + "] " + ex.getMessage());
    System.err.println("建议: " + ex.getHint());
}

AiException 是 RuntimeException，不必在方法签名声明。hint 与 error-catalog 逐字一致，绑定不改写，可原样展示给最终用户。

功能概览

类别	属性	类型	访问	说明
基类	AiException.getCode	int	只读	darra_error_code 整数值
	AiException.getMessage	String	只读	C 的 message（什么错）
	AiException.getHint	String	只读	修复建议（error-catalog 标准文案，可为空串）
	AiException.throwByCode	void	静态	JNI 失败路径入口：按码抛对应子类。code==0 为 no-op。未知码抛基类
IO / 容器	IoNotFoundException	AiException	抛出	DARRA_IO_NOT_FOUND (1)：文件不存在（容器/授权/图片/离线包路径错）
	IoDeniedException	AiException	抛出	DARRA_IO_DENIED (2)：文件存在但读/写被拒
	BadContainerException	AiException	抛出	DARRA_BAD_CONTAINER (3)：.darmodel 损坏 / 非 DARM1 / 被截断篡改
	BadLicenseException	AiException	抛出	DARRA_BAD_LICENSE (4)：.darmkey 损坏或与容器不配对
授权	PasswordRequiredException	AiException	抛出	DARRA_PASSWORD_REQUIRED (5)：该容器需要密码但调用方没给
	PasswordWrongException	AiException	抛出	DARRA_PASSWORD_WRONG (6)：密码错误
	MachineMismatchException	AiException	抛出	DARRA_MACHINE_MISMATCH (7)：绑机授权在非目标机器上使用
	TrialExhaustedException	AiException	抛出	DARRA_TRIAL_EXHAUSTED (8)：试用计次已用完
环境	UnsupportedPayloadException	AiException	抛出	DARRA_UNSUPPORTED_PAYLOAD (9)：载荷类型在当前平台/Provider 下不支持。Windows 收到 rknn 载荷走此码。.pt / .pth 走此码
	UnsupportedPlatformException	AiException	抛出	DARRA_UNSUPPORTED_PLATFORM (10)：整个 OS/架构不在支持矩阵。Windows 上指名 edge-rknn 走此码
	ProviderMissingException	AiException	抛出	DARRA_PROVIDER_MISSING (11)：需要的运行时 Provider 包未安装
	ProviderAbiMismatchException	AiException	抛出	DARRA_PROVIDER_ABI_MISMATCH (12)：Provider 包与内核 ABI 不匹配
	HardwareMissingException	AiException	抛出	DARRA_HARDWARE_MISSING (13)：未探测到所需硬件
	DriverTooOldException	AiException	抛出	DARRA_DRIVER_TOO_OLD (14)：驱动版本低于 Provider 包要求（SDK 不代装）
安装 / 内部	NetworkFailedException	AiException	抛出	DARRA_NETWORK_FAILED (15)：清单 / 运行时包下载失败
	ChecksumMismatchException	AiException	抛出	DARRA_CHECKSUM_MISMATCH (16)：下载包或离线包 sha256 校验不过
	CancelledException	AiException	抛出	DARRA_CANCELLED (17)：操作被取消（AiRuntime.ensureCancel）
	InternalException	AiException	抛出	DARRA_INTERNAL (18)：SDK 内部错误；也用于调用方参数契约违反

方法

getCode()

public int getCode()

darra_error_code 整数值。

返回值:

• int — 错误码

getHint()

public String getHint()

修复建议，与 error-catalog 的 hint 文案逐字一致。无建议时为空串。绑定不改写。

返回值:

• String — hint

AiException.throwByCode(int code, String message, String hint)

public static void throwByCode(int code, String message, String hint)

JNI 失败路径入口：按码抛出对应子类。code==0 为 no-op。未知码抛基类，不丢信息。

参数:

• code (int) — darra_error_code 整值
• message (String) — C 的 message
• hint (String) — C 的 hint

码对照

码	C 常量	Java 异常	常量
0	DARRA_OK	（不抛）	AiException.OK
1	DARRA_IO_NOT_FOUND	AiException.IoNotFoundException	IO_NOT_FOUND
2	DARRA_IO_DENIED	AiException.IoDeniedException	IO_DENIED
3	DARRA_BAD_CONTAINER	AiException.BadContainerException	BAD_CONTAINER
4	DARRA_BAD_LICENSE	AiException.BadLicenseException	BAD_LICENSE
5	DARRA_PASSWORD_REQUIRED	AiException.PasswordRequiredException	PASSWORD_REQUIRED
6	DARRA_PASSWORD_WRONG	AiException.PasswordWrongException	PASSWORD_WRONG
7	DARRA_MACHINE_MISMATCH	AiException.MachineMismatchException	MACHINE_MISMATCH
8	DARRA_TRIAL_EXHAUSTED	AiException.TrialExhaustedException	TRIAL_EXHAUSTED
9	DARRA_UNSUPPORTED_PAYLOAD	AiException.UnsupportedPayloadException	UNSUPPORTED_PAYLOAD
10	DARRA_UNSUPPORTED_PLATFORM	AiException.UnsupportedPlatformException	UNSUPPORTED_PLATFORM
11	DARRA_PROVIDER_MISSING	AiException.ProviderMissingException	PROVIDER_MISSING
12	DARRA_PROVIDER_ABI_MISMATCH	AiException.ProviderAbiMismatchException	PROVIDER_ABI_MISMATCH
13	DARRA_HARDWARE_MISSING	AiException.HardwareMissingException	HARDWARE_MISSING
14	DARRA_DRIVER_TOO_OLD	AiException.DriverTooOldException	DRIVER_TOO_OLD
15	DARRA_NETWORK_FAILED	AiException.NetworkFailedException	NETWORK_FAILED
16	DARRA_CHECKSUM_MISMATCH	AiException.ChecksumMismatchException	CHECKSUM_MISMATCH
17	DARRA_CANCELLED	AiException.CancelledException	CANCELLED
18	DARRA_INTERNAL	AiException.InternalException	INTERNAL

子类全部是 AiException 的 public static final class 嵌套类，包名 xyz.darra.ai。

常见场景

明文 .onnx 传给 AiSession.open → BadContainerException。明文请改用 openPlain。

Windows 无 RKNN：

• 指名 edge-rknn → UnsupportedPlatformException
• 容器 / 明文是 rknn 载荷 → UnsupportedPayloadException

RKNN 只在 linux-arm64。不要在 Windows 上试降级，SDK 不静默换 Provider。

.pt / .pth → UnsupportedPayloadException。Paddle 是运行时载荷，明文 openPlain 接 .pdmodel（伴生 .pdiparams），不走这条拒绝路径。

进度回调里调 ensureCancel 视为违反契约。取消必须从回调外的线程（含 UI 线程）调。

close 后再 inferImage / metaJson → InternalException（「会话已关闭」）。