【免费下载链接】CangjieCorpus
本仓库为仓颉编程语言语料库,聚焦 仓颉编程语言 核心知识体系,整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源,经结构化处理与专业标注,构建为支持 RAG(检索增强生成)技术 的高质量知识基座,适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用,推动鸿蒙开发生态智能化升级!
导读
本文基于开源仓颉语料库中 Media 错误码参考文档,系统梳理仓颉开发场景下 ohos.multimedia.media(媒体服务)模块特有的 18 个业务错误码,涵盖内存分配失败、状态机操作不允许、IO 异常、操作超时、播放服务死亡、音频焦点冲突以及网络链路、SSL 证书等一系列错误。读完本文,你将能对照错误码快速定位故障根因,并掌握"销毁实例—排查环境—重新创建"的标准处置方法论,同时理解这些错误码在 AVImageGenerator 等媒体 API 调用链中的具体抛出场景。
一、错误码机制概述:模块特有错误码与通用错误码
Media Kit(媒体服务)当前在 OpenHarmony 中为 Beta 特性,其仓颉 API 参考目录见 MediaKit 参考文档入口。在仓颉应用中调用媒体接口时,错误以 BusinessException 异常形式抛出,开发者可通过异常携带的 message 获取错误信息。
媒体模块遵循"模块特有错误码 + 通用错误码"的双层错误体系:
- 模块特有错误码:即本文讲解的
5400101~5400107、5411001~5411011,仅针对ohos.multimedia.media媒体服务定义; - 通用错误码:适用于所有模块的公共错误,如
201(权限校验失败)、401(参数检查失败)、801(设备不支持该 API)等,详见通用错误码说明文档。
说明:原文档明确提示,以下仅介绍本模块特有错误码,通用错误码请参考通用错误码说明文档。排查媒体功能问题时,应先确认错误码是否属于本模块特有范围,若为
201/401/801等通用码,需按通用错误码文档处理。
从错误码编号区间可以直观看出其归属:540010x 段为本地媒体处理类错误(内存、状态机、IO、超时、服务、格式、音频焦点),541100x~541101x 段为网络媒体相关错误(地址解析、连接、SSL、权限与资源)。这与媒体服务既处理本地资源、又支持网络流的架构特征一致。
二、本地媒体错误码(5400101~5400107)
本组错误码覆盖媒体实例的创建、状态流转、IO 交互、超时控制、服务生命周期、格式规格与音频焦点等本地处理链路,是媒体功能最常遇到的错误区间。
5400101 内存分配失败
| 项目 | 内容 |
|---|---|
| 错误信息 | No memory. |
| 错误描述 | 分配内存失败。 |
| 可能原因 | ① 实例数量超过 16 个;② new 或 malloc 流程失败导致空指针。 |
| 处理步骤 | 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
深入解读:该错误码意味着媒体服务侧内存资源耗尽或分配流程异常。原因①明确指出同一场景下媒体实例数量存在上限(16 个),开发者在长生命周期页面中若频繁创建 AVImageGenerator、AVPlayer 等实例而不及时释放,将触发该错误;原因②则指向底层 new/malloc 失败产生的空指针。从 API 参考 看,createAVImageGenerator() 与 release() 的异常表中均列出 5400101,印证了"创建与释放必须成对"的使用约束——调用 release() 及时释放资源是规避该错误码的关键手段。
5400102 当前状态机不支持此操作
| 项目 | 内容 |
|---|---|
| 错误信息 | Operation not allowed. |
| 错误描述 | 当前操作不允许。 |
| 可能原因 | 当前状态机不支持此操作。 |
| 处理步骤 | 确认当前状态是否支持当前操作,把实例切换到正确的状态进行正确的操作。 |
深入解读:媒体组件(如播放器、录制器、缩略图生成器)内部按状态机运转,接口调用必须符合状态迁移顺序。以 AVImageGenerator 为例,其 fdSrc 属性设置与 fetchFrameByTime() 调用均可能抛出 5400102——在未正确设置数据源或实例已释放的状态下调用取帧接口,就会触发"操作不允许"。排查时需对照 API 文档确认实例所处状态与操作前置条件。
5400103 出现IO错误
| 项目 | 内容 |
|---|---|
| 错误信息 | I/O error. |
| 错误描述 | 出现 IO 错误。 |
| 可能原因 | 媒体与其他模块的数据交互发生问题(图形、音频、网络、HDI、相机)。 |
| 处理步骤 | 确认网络是否通畅,并销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
深入解读:该错误是媒体子系统与外部模块数据交互失败的统称,原因横跨图形、音频、网络、HDI(硬件设备接口)、相机等多个数据通道。处理步骤中的"确认网络是否通畅"提示了网络流媒体场景下 IO 错误与网络状态的高度关联;若为本地资源场景,则需进一步检查文件描述符是否有效、资源是否被其他模块独占。
5400104 操作超时
| 项目 | 内容 |
|---|---|
| 错误信息 | Operation timeout. |
| 错误描述 | 操作超时。 |
| 可能原因 | ① 网络超时:默认网络超时时间为 15 秒,从开始缓存的事件上报后开始计时,超时后会上报该错误信息;② 访问其他模块超时。 |
| 处理步骤 | ① 确认网络是否通畅;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
深入解读:这是本错误码文档中唯一明确给出时间参数的错误。网络超时默认 15 秒,且计时起点为"开始缓存的事件上报之后"——也就是说,从媒体服务开始缓存上报事件起,若 15 秒内相关操作未完成,即上报 Operation timeout.。开发者可据此在业务侧设置合理的超时等待窗口,避免在超时错误上报后仍对实例做无效操作。
5400105 播放服务死亡
| 项目 | 内容 |
|---|---|
| 错误信息 | Service died. |
| 错误描述 | 播放服务死亡。 |
| 可能原因 | 播放服务死亡。 |
| 处理步骤 | 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
深入解读:该错误码标识媒体播放服务进程异常退出,属于服务端生命周期类错误。一旦出现,当前实例已不可用,必须销毁重建。这种"服务死亡—重建实例"的处置模式在 5400101、5400103、5400104 等错误中反复出现,构成了媒体错误处理的通用动作模板。
5400106 不支持的规格
| 项目 | 内容 |
|---|---|
| 错误信息 | Unsupported format. |
| 错误描述 | 不支持的规格。 |
| 可能原因 | 不支持的文件或者格式。 |
| 处理步骤 | 当前使用的格式规格不支持,用户需要切换为支持的格式规格。 |
深入解读:此错误由输入媒体文件或参数的格式规格超出能力范围导致。在 AVImageGenerator.fetchFrameByTime() 的异常表中明确列出 5400106,意味着当传入的 PixelMapParams 输出规格或视频源格式不被支持时即抛出该码。处理上只能由开发者切换到受支持的格式规格,无法通过重试解决。
5400107 音频焦点冲突
| 项目 | 内容 |
|---|---|
| 错误信息 | Audio interrupted. |
| 错误描述 | 音频焦点冲突导致录制失败。 |
| 可能原因 | 有其他进程占用了音频焦点,导致无法获取音频焦点。 |
| 处理步骤 | 销毁当前实例,并确认当前是否有其他进程在进行录制;如果可以停止其他进程的占用,则可以重新创建。 |
深入解读:该错误码专门针对录音场景。OpenHarmony 的音频焦点机制保证同一时刻仅一个应用可持有录音焦点,当其他进程(如通话、其他录音应用)占用焦点时,本应用录制即失败并上报 Audio interrupted.。处置前必须先行确认并释放其他进程的焦点占用,单纯重建实例无法解决焦点被占的根本问题。
三、网络媒体错误码(5411001~5411011)
本组错误码对应网络流媒体场景,覆盖服务端地址解析、网络连接、SSL 证书校验、权限与资源等环节,从 5411001 到 5411011 构成了一条完整的"建连—校验—传输"排查链路。
5411001 解析或链接服务端地址错误
| 项目 | 内容 |
|---|---|
| 错误信息 | Can not find host. |
| 错误描述 | 解析或链接服务端地址错误。 |
| 可能原因 | ① 链接服务端地址错误;② 链接服务端地址解析失败。 |
| 处理步骤 | 当前使用的链接服务端地址错误或无法被解析,需改用其他链接服务端地址。 |
5411002 网络连接超时
| 项目 | 内容 |
|---|---|
| 错误信息 | Connection time out. |
| 错误描述 | 网络连接超时。 |
| 可能原因 | 网络异常。 |
| 处理步骤 | ① 确认网络是否通畅;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
5411003 网络异常导致的数据或链路异常
| 项目 | 内容 |
|---|---|
| 错误信息 | NetWork abnormal. |
| 错误描述 | 网络异常导致的数据或链路异常。 |
| 可能原因 | 网络异常。 |
| 处理步骤 | 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
5411004 网络被禁用
| 项目 | 内容 |
|---|---|
| 错误信息 | NetWork unavailable. |
| 错误描述 | 网络被禁用导致的错误。 |
| 可能原因 | 网络被禁用。 |
| 处理步骤 | ① 确认网络是否被禁用;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
5411005 无权限,访问被拒绝
| 项目 | 内容 |
|---|---|
| 错误信息 | No permission. |
| 错误描述 | 无访问权限。 |
| 可能原因 | 无访问权限。 |
| 处理步骤 | ① 确认是否有访问权限;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
深入解读:5411005 与通用错误码 201(权限校验失败)容易混淆,需注意区分:201 是应用未申请 API 调用权限(如媒体服务所需的 ohos.permission.MICROPHONE),属通用码范畴;而 5411005 是媒体网络服务端的访问权限被拒,需确认对目标服务端地址是否具备访问权限。
5411006 客户端请求参数错误或超出处理能力
| 项目 | 内容 |
|---|---|
| 错误信息 | Network access denied. |
| 错误描述 | 客户端请求参数错误或超出处理能力。 |
| 可能原因 | 客户端请求参数错误或超出处理能力。 |
| 处理步骤 | ① 确认请求参数是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
5411007 无可用资源
| 项目 | 内容 |
|---|---|
| 错误信息 | Cannot find available network resources. |
| 错误描述 | 无可用网络资源。 |
| 可能原因 | 链接服务端地址异常。 |
| 处理步骤 | ① 确认链接服务端地址是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
5411008 服务端校验客户端证书失败
| 项目 | 内容 |
|---|---|
| 错误信息 | SSL client cert needed. |
| 错误描述 | SSL 客户端不可信,服务端校验客户端证书失败。 |
| 可能原因 | 未携带证书、证书不合法、证书过期。 |
| 处理步骤 | ① 确认 SSL 证书是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
5411009 SSL连接失败
| 项目 | 内容 |
|---|---|
| 错误信息 | SSL connection failed. |
| 错误描述 | SSL 链接失败。 |
| 可能原因 | SSL 链接失败。 |
| 处理步骤 | ① 确认 SSL 链接是否已失效;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
5411010 客户端校验服务端证书失败
| 项目 | 内容 |
|---|---|
| 错误信息 | SSL server cert needed. |
| 错误描述 | SSL 服务端不可信,客户端校验服务端证书失败。 |
| 可能原因 | 未携带证书、证书不合法、证书过期。 |
| 处理步骤 | ① 确认 SSL 证书是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
深入解读:5411008 与 5411010 构成 SSL 双向校验的两端视角:前者是服务端校验客户端证书(SSL client cert needed.),后者是客户端校验服务端证书(SSL server cert needed.),两者的可能原因均为"未携带证书、证书不合法、证书过期"。HTTPS 网络流媒体场景下,开发者应优先核对证书链是否完整、是否在有效期内,再执行实例重建流程。
5411011 网络协议的原因导致请求不受支持
| 项目 | 内容 |
|---|---|
| 错误信息 | Unsupportted request. |
| 错误描述 | 客户端请求参数错误或超出处理能力。 |
| 可能原因 | 客户端请求参数错误或超出处理能力。 |
| 处理步骤 | ① 确认客户端请求参数是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。 |
注意:该错误码的"错误描述"与"可能原因"原文均写为"客户端请求参数错误或超出处理能力"(与
5411006相同),但从错误信息Unsupportted request.(原文拼写)与标题"网络协议的原因导致请求不受支持"看,其本质是请求因协议原因不被服务端支持。实际排查时应以错误信息与标题为准,重点核查请求是否符合服务端协议要求。
四、错误码与媒体 API 的对应关系
了解"哪个接口可能抛哪个错误码",能显著缩小排查范围。在 ohos.multimedia.media API 参考 中,各接口均通过异常表声明其可抛出的 Media 错误码,以当前 Beta 版提供的 AVImageGenerator(视频缩略图获取)能力为例:
| API | 可抛出的 Media 错误码 |
|---|---|
createAVImageGenerator() | 5400101(No memory.) |
prop fdSrc(设置数据源) | 5400101、5400102 |
fetchFrameByTime()(获取指定时间图像) | 5400101、5400102、5400106 |
release()(释放资源) | 5400101 |
对应关系印证了错误码的实际触发场景:
5400101贯穿实例创建到释放的完整生命周期,与"实例数量上限 16"和资源释放不及时直接相关;5400102出现在设置数据源与取帧阶段,对应状态机校验(如未设置fdSrc就调用fetchFrameByTime());5400106仅在取帧时出现,与视频源格式或PixelMapParams输出规格不支持相关。
仓颉侧的系统能力声明可见于 SysCap 能力列表,其中 SystemCapability.Multimedia.Media.AVImageGenerator、SystemCapability.Multimedia.Media.AVPlayer、SystemCapability.Multimedia.Media.AVRecorder、SystemCapability.Multimedia.Media.AVMetadataExtractor、SystemCapability.Multimedia.Media.AVTranscoder 等即对应媒体服务各能力点;若设备不具备相应能力(通用错误码 801),接口将不可用。
五、错误处理实战:仓颉代码中的捕获与处置
5.1 基础捕获模式
仓颉中媒体接口以 BusinessException 抛出错误,标准捕获写法如下(源自 API 参考示例):
// index.cj
import kit.MediaKit.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
let generator = createAVImageGenerator()
// ... 设置数据源、获取缩略图等操作
} catch (e: BusinessException) {
Hilog.error(0, "AppLogCj", e.message)
}
其中 Hilog 用于输出错误信息到日志,便于对照本文错误码表定位问题。需要说明的是,媒体接口的错误码通过 BusinessException 的 message 字段携带,5400101~5411011 各码对应的英文错误信息即为 message 的内容,可据此在日志中快速匹配。
5.2 按错误码分流的处置模板
综合前文各错误码的处理步骤,可提炼出如下统一处置逻辑:
// 伪代码示例:按错误码选择处置动作
try {
// 媒体操作
} catch (e: BusinessException) {
match (e.code) {
// 内存/IO/超时/服务死亡类:销毁重建
case 5400101 | 5400103 | 5400104 | 5400105 =>
generator.release() // 销毁当前实例
// 重新创建实例并重试;若重建失败则停止相关操作
// 状态机类:调整操作顺序或实例状态
case 5400102 =>
// 确认当前状态是否支持该操作,切换实例到正确状态
// 格式规格类:切换资源或参数规格
case 5400106 =>
// 切换为支持的格式规格
// 音频焦点类:确认并释放其他进程占用
case 5400107 =>
// 确认是否有其他进程在录制,停止占用后重建
// 网络类:先确认网络/证书/地址,再重建实例
case 5411001 | 5411002 | ... | 5411011 =>
// 确认网络、服务端地址、SSL 证书、权限后重建实例
_ => ()
}
}
注意:上例中
e.code为示意性写法,具体获取错误码的字段名请以所使用 SDK 的BusinessException定义为准。处置原则与官方文档一致:凡涉及实例异常(内存、IO、超时、服务死亡、网络)的错误,统一走"销毁实例 → 确认环境(网络/证书/地址/权限/焦点)→ 重新创建,重建失败则停止相关操作"的流程。
5.3 完整调用流程中的错误预防
结合使用 AVImageGenerator 提取视频指定时间图像(仓颉)开发指导,媒体功能的完整生命周期为"创建实例 → 设置资源 → 获取数据 → 释放资源",在各环节落实预防措施可显著降低上述错误码的触发概率:
- 创建实例:调用
createAVImageGenerator()创建,注意实例总数不超过 16 个,用完即release(); - 设置资源:通过
ResourceManager.getRawFd或应用沙箱路径取得文件描述符后赋值给fdSrc;不同AVImageGenerator/AVMetadataExtractor实例操作同一资源时需多次打开文件描述符,不要共用同一 fd,且 fd 传给实例后不得再用于其他读写操作,否则将引发资源竞争(对应5400102状态机错误与 IO 类异常); - 获取数据:
fetchFrameByTime(timeUs, queryOption, param)中timeUs为时间点(微秒)、queryOption决定与关键帧的时间对应关系、param为输出缩略图格式参数(width/height应大于 0 且不大于原始视频尺寸,否则不缩放),参数不合法可触发5400106; - 释放资源:
release()销毁实例。
六、错误码速查总表与排查优先级
为便于日常开发快速查阅,将全部 18 个 Media 模块特有错误码汇总如下:
| 错误码 | 错误信息 | 一句话定位 | 核心处置动作 |
|---|---|---|---|
| 5400101 | No memory. | 内存分配失败,实例超 16 个或 malloc/new 失败 | 销毁重建,失败则停止 |
| 5400102 | Operation not allowed. | 状态机不支持当前操作 | 切换实例到正确状态 |
| 5400103 | I/O error. | 媒体与图形/音频/网络/HDI/相机交互异常 | 确认网络后销毁重建 |
| 5400104 | Operation timeout. | 操作超时(网络默认 15 秒) | 确认网络后销毁重建 |
| 5400105 | Service died. | 播放服务死亡 | 销毁重建,失败则停止 |
| 5400106 | Unsupported format. | 文件或格式规格不支持 | 切换为支持的规格 |
| 5400107 | Audio interrupted. | 音频焦点被其他进程占用 | 停止占用后重建 |
| 5411001 | Can not find host. | 服务端地址错误或解析失败 | 更换链接地址 |
| 5411002 | Connection time out. | 网络连接超时 | 确认网络后销毁重建 |
| 5411003 | NetWork abnormal. | 网络异常致数据/链路异常 | 销毁重建,失败则停止 |
| 5411004 | NetWork unavailable. | 网络被禁用 | 确认网络后销毁重建 |
| 5411005 | No permission. | 服务端访问权限被拒 | 确认权限后销毁重建 |
| 5411006 | Network access denied. | 请求参数错误或超出能力 | 确认参数后销毁重建 |
| 5411007 | Cannot find available network resources. | 服务端地址异常无可用资源 | 确认地址后销毁重建 |
| 5411008 | SSL client cert needed. | 服务端校验客户端证书失败 | 确认证书后销毁重建 |
| 5411009 | SSL connection failed. | SSL 链接失败 | 确认链接后销毁重建 |
| 5411010 | SSL server cert needed. | 客户端校验服务端证书失败 | 确认证书后销毁重建 |
| 5411011 | Unsupportted request. | 请求因网络协议原因不受支持 | 确认请求参数后销毁重建 |
排查优先级建议:遇到媒体错误时,建议按下述顺序定位:
- 先判断错误码是否属于本模块特有码(5400101~5400107、5411001~5411011),否则转到通用错误码说明文档处理(如
201权限、401参数、801能力不支持); - 对网络类错误(5411001~5411011),先确认服务端地址、网络连通性、SSL 证书与访问权限,再执行实例销毁重建;
- 对本地类错误(5400101~5400107),先确认实例数量、调用顺序、资源描述符与音频焦点占用情况,再执行实例销毁重建;
- 无论哪类错误,都遵循统一原则:销毁当前实例并重新创建,若重新创建失败则停止相关操作,避免在失效实例上持续重试导致资源泄漏。
总结
Media 错误码文档以"错误信息—错误描述—可能原因—处理步骤"四要素结构,系统定义了媒体服务的 18 个特有错误码。理解这组错误码的关键在于两点:一是按编号区间区分本地媒体错误(540010x,内存、状态机、IO、超时、服务、规格、音频焦点)与网络媒体错误(541100x~541101x,地址、连接、SSL、权限、资源);二是掌握贯穿始终的通用处置方法论——先确认环境因素(网络、证书、地址、权限、焦点、实例数量),再销毁重建实例,重建失败即停止相关操作。结合 AVImageGenerator 等 API 参考 中各接口声明的错误码异常表,开发者即可在仓颉应用中实现精准的错误捕获、日志定位与故障恢复。
【免费下载链接】CangjieCorpus
本仓库为仓颉编程语言语料库,聚焦 仓颉编程语言 核心知识体系,整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源,经结构化处理与专业标注,构建为支持 RAG(检索增强生成)技术 的高质量知识基座,适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用,推动鸿蒙开发生态智能化升级!
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



