YOLO 错误码说明 - YoloErrorCodes

概述

以下 YOLO 接口在失败时返回负数，其绝对值即为错误码，与 GetLastError() 返回值一致：

• 加载类：YoloLoadModel / YoloLoadModelEx / YoloLoadModelMemory / YoloLoadModelMemoryEx
• 管理类：YoloReleaseModel / YoloSetModelConfig / YoloSetModelConfigByKey / YoloWarmup / YoloClearError
• 加解密类：YoloEncryptModel / YoloEncryptModelEx / YoloDecryptModel / YoloDecryptModelEx

成功时：

• 加载类：返回 大于 0 的模型句柄
• 操作类：返回 1

推理类接口（YoloDetect* / YoloClassify* / …）仍返回 JSON 字符串；失败时 JSON 含 "success":false，同时会写入 GetLastError()，便于统一排查。

失败时建议同时调用：

• GetLastError()：获取错误码（正整数，如 8006）
• GetLastErrorString()：获取中文说明（用完后 FreeStringPtr 释放）
• YoloGetLastError()：获取后端详细错误文本/JSON（GPU 设备列表等）

long handle = ola.YoloLoadModelEx("models/yolo11n.onnx", "", "person|car", 1, 0, -1);
if (handle <= 0) {
    int err = GetLastError();                 // 例如 8006
    int code = handle < 0 ? (int)(-handle) : err;
    char* msg = (char*)GetLastErrorString();
    char* yoloMsg = (char*)ola.YoloGetLastError();
    // 根据 code 排查，见下表
    FreeStringPtr((int64_t)msg);
    FreeStringPtr((int64_t)yoloMsg);
} else {
    // handle 可用于 Detect / Classify / ...
    ola.YoloReleaseModel(handle);
}

重要：判断加载是否成功请用 handle > 0，不要再用 handle != 0（失败时返回负错误码）。

通用错误（10xx）

返回值	GetLastError	说明	排查建议
-1001	1001	权限不足 / 未登录	Login/Reg；FeatureList 须含 Yolos / YOLO 特性
-1003	1003	参数无效	instance 无效等

YOLO 错误（80xx）

返回值	GetLastError	说明	排查建议
-8001	8001	YOLO 参数无效	空路径、非法内存地址/长度、类型越界等
-8002	8002	模型/标签/图片文件不存在	检查路径、WorkPath、文件是否可读
-8003	8003	非欧拉加密包或包格式无效	明文请用 YoloLoadModelEx；加密包用 YoloLoadModel
-8004	8004	加密包密码错误或为空	检查 password
-8005	8005	加密包解密失败	密码、包损坏、头信息不完整
-8006	8006	后端加载模型失败	权重与 inferenceType/modelType 是否匹配；看 YoloGetLastError
-8007	8007	无效的 YOLO 模型句柄	是否已 Release；句柄是否来自本实例
-8008	8008	模型加密打包失败	写出路径权限、磁盘空间
-8009	8009	模型配置失败	JSON 字段名是否合法；句柄是否有效
-8010	8010	推理设备不可用 / GPU 索引越界	NCNN Vulkan 须用可见设备索引；可改 -1 CPU
-8011	8011	图像无效或读取失败	imagePtr / 文件路径
-8012	8012	屏幕区域截图失败	绑定窗口、区域坐标、截图后端
-8013	8013	当前构建未启用 YOLO	使用带 YOLO 的发布包
-8099	8099	YOLO 操作内部异常	联系支持并提供日志
-9999	9999	未知错误	查看日志 / YoloGetLastError

相关接口

接口	说明
YoloLoadModelEx	加载明文模型
YoloLoadModel	加载加密包
YoloGetLastError	后端详情（亦可用插件 GetLastErrorString）
GetLastError	读取错误码
YOLO 模块总览	流水线与选型