以下仅介绍本模块特有错误码，通用错误码请参考通用错误码说明文档。
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
蓝牙服务子系统错误码
本文导读
说明
2900001 蓝牙服务停止
错误信息
Service stopped.
错误描述
蓝牙服务已停止，蓝牙服务相关的接口无法调用。
可能原因
蓝牙服务启动异常。
处理步骤
重新执行打开或关闭蓝牙。
2900003 蓝牙开关关闭
错误信息
Bluetooth disabled.
错误描述
蓝牙开关已关闭。
可能原因
蓝牙开关被用户手动关闭，或因系统异常导致蓝牙服务自动关闭。
处理步骤
重新执行打开蓝牙开关。
2900004 配置文件不支持
错误信息
Profile not supported.
错误描述
配置文件是不支持的。
可能原因
该配置文件在当前设备环境不支持。
处理步骤
检查设备是否支持该配置文件功能，若不支持则停止调用。
2900005 蓝牙设备未连接
错误信息
Device not connected.
错误描述
该设备蓝牙未连接。
可能原因
设备配对异常。
处理步骤
重新打开蓝牙开关，执行配对流程。
2900006 超最大连接数
错误信息
The maximum number of connections has been reached.
错误描述
超过最大连接数量。
可能原因
超出设备最大连接数量。
处理步骤
检查已配对设备数量，若超出阈值，请先断开部分已连接的设备，再重新尝试连接。
2900007 异步接口调用超时
错误信息
Asynchronous interface invoking timeout.
错误描述
异步接口调用超时。
可能原因
远端设备无响应。
处理步骤
超时后重试；若和远端设备存在链路，可以断开后，再重试。
2900008 空指针
错误信息
The value of proxy is a null pointer.
错误描述
pimpl或proxy为空。
可能原因
设备配对异常。
处理步骤
尝试重新打开蓝牙开关，执行配对流程后，再调用相关接口。
2900009 硬件资源不足
错误信息
Fails to start scan as it is out of hardware resources.
错误描述
由于硬件资源不足，无法启动本次扫描。
可能原因
当前系统中本应用或其他应用已启动的扫描通道过多，导致硬件资源不足。
处理步骤
本应用未启动过扫描，可重新关开蓝牙，释放其他应用占用的扫描资源；
本应用已启动过其他通道的扫描，可调用停止扫描接口，停止其他已启动的扫描，释放硬件资源后再重新启动本次扫描。
2900010 资源达到上限
错误信息
Resources have reached the upper limit.
错误描述
资源达到上限。
可能原因
应用申请资源过多，需要释放资源。
处理步骤
调用对应的资源释放接口释放资源，例如调用停止扫描接口或断开已建立的连接后重试。
2900011 操作频繁
错误信息
The operation is busy. The last operation is not complete.
错误描述
操作忙碌，上一个执行的操作还未完成。
可能原因
上一个执行的操作还未完成即执行本次操作，例如readCharacteristicValue未结束即进行下一次操作。
其他涉及的接口有writeCharacteristicValue、readDescriptorValue、writeDescriptorValue、getRssiValue、setCharacteristicChangeNotification、setCharacteristicChangeIndication，如调用未完成均可能阻塞下一次操作。
处理步骤
异步接口需等待callback或promise返回后再执行下一次操作。
2900013 前置操作超时
错误信息
The user does not respond.
错误描述
用户未回复前置操作。
可能原因
用户在系统规定的超时时限内未完成前置操作，导致前置操作超时。
处理步骤
重新执行前置操作。
2900014 用户拒绝此操作
错误信息
User refuse the action.
错误描述
用户执行拒绝操作。
可能原因
用户拒绝前置操作的请求。
处理步骤
重新执行前置操作。
2900015 参数格式与规范不一致
错误信息
Parameter format mismatch with specification.
错误描述
参数格式与规范不一致。
可能原因
例如，参数长度不符合规范，或本应使用大写字母的参数却传入了小写字母。
处理步骤
检查参数格式，是否与规范保持一致。
2900016 设备未配对
错误信息
Device unpaired.
错误描述
设备未配对。
可能原因
查询的地址与设备未配对。
处理步骤
在蓝牙设置界面检查是否与该设备配对。
2900099 操作失败
根据实际错误原因的不同，上报不同的错误信息，具体如下。
操作失败
错误信息
Operation failed.
错误描述
操作失败。发生内部系统错误，包括SA异常，IPC异常等。
可能原因
蓝牙接口调用失败的通用错误码，常见可能原因如下：
- 未满足接口调用的前置依赖条件。
- 指定的虚拟地址不存在。
处理步骤
检查接口调用的前置依赖条件。
无效参数
错误信息
Operation failed. Invalid parameter.
错误描述
入参无效。
可能原因
函数入参不在有效范围内。
处理步骤
检查接口调用传参是否符合接口说明或协议规范。
GATT特征值为空
错误信息
Operation failed. GATT character is nullptr.
错误描述
基于通用属性协议（Generic Attribute Profile，GATT）的特征值为空。
可能原因
特征值为空。
处理步骤
检查接口调用传参。
调用接口时前一个接口调用流程未完成
错误信息
Operation failed. Please call the interface only after the previous callback has been completed.
错误描述
在前一个接口回调完成后，再调用该接口。
可能原因
前一个接口的回调未完成。
处理步骤
等待前一个接口的回调完成。
对端设备未被发现或被记录
错误信息
Operation failed. Address has not been discovered or recorded.
错误描述
设备尚未被发现或被记录。
可能原因
配对的对端设备未被发现或被记录。
处理步骤
配对已被发现或记录的对端设备。
蓝牙开关已经打开
错误信息
Operation failed. Bluetooth switch state is turn on.
错误描述
蓝牙开关已经打开。
可能原因
蓝牙开关已经打开。
处理步骤
检查蓝牙开关状态，在蓝牙开关状态无误时重复操作。
蓝牙开关状态正在切换
错误信息
Operation failed. Bluetooth switch state is turning state.
错误描述
蓝牙开关状态正在切换中。
可能原因
蓝牙开关状态正在切换中。
处理步骤
等待蓝牙开关状态切换完成，再尝试操作。
蓝牙开关在受限状态
错误信息
Operation failed. In restrict bluetooth state.
错误描述
蓝牙开关在受限状态。
可能原因
蓝牙开关在受限状态。
处理步骤
等待蓝牙开关退出受限状态后，再尝试操作。
云设备正在绑定
错误信息
Operation failed. Cloud device is bonding.
错误描述
云设备正在绑定中。
可能原因
云设备正在绑定中。
处理步骤
等待云设备绑定完成后，再尝试操作。
设备处于发现流程中或处于已发现状态
错误信息
Operation failed. In DISCOVERYING or DISCOVERY_STARTED state.
错误描述
在发现流程中或处于已发现状态。
可能原因
设备处于发现流程中或处于已发现状态。
处理步骤
请勿重复发起蓝牙扫描。
由于硬件资源不足无法启动扫描
错误信息
Operation failed. Fails to start scan as it is out of hardware resources.
错误描述
由于硬件资源不足，无法启动本次扫描。
可能原因
当前系统中本应用或其他应用已启动的扫描通道过多，导致硬件资源不足。
处理步骤
- 本应用未启动过扫描，可重新关开蓝牙，释放其他应用占用的扫描资源。
- 本应用已启动过其他通道的扫描，可调用停止扫描接口，停止其他已启动的扫描，释放硬件资源后再重新启动本次扫描。
GATT未连接
错误信息
Operation failed. GATT not in connected state.
错误描述
GATT不在已连接状态。
可能原因
GATT未连接。
处理步骤
请先连接GATT，再尝试操作。
业务扫描期间不允许发起连接
错误信息
Operation failed. Not allowed to connect during scanning.
错误描述
扫描期间不允许连接。
可能原因
业务扫描期间不允许发起连接。
处理步骤
请先完成业务扫描，再发起连接。
无效蓝牙地址或传输类型
错误信息
Operation failed. Invalid bluetooth addr or transport type.
错误描述
无效蓝牙地址或传输类型。
可能原因
入参包含无效的蓝牙地址或传输类型。
处理步骤
检查入参是否符合协议要求。
IPC数据传输失败
错误信息
Operation failed. IPC trans failed.
错误描述
IPC数据传输失败。
可能原因
数据传输异常。
处理步骤
请检查传入数据，再尝试操作。
已达到最大连接数
错误信息
Operation failed. Max connections has reached.
错误描述
已达到最大连接数。
可能原因
已达到最大连接数。
处理步骤
清理已连接设备后，再尝试发起新连接。
设备已连接
错误信息
Operation failed. This device has connected.
错误描述
该设备已连接。
可能原因
该设备已连接。
处理步骤
该设备已连接。请勿重复操作。
设备未连接
错误信息
Operation failed. This device isn't connected.
错误描述
该设备未连接。
可能原因
该设备未连接。
处理步骤
设备未连接，当前操作无效。请先连接设备。
GATT服务端准备写入队列已满
错误信息
Operation failed. The prepare write queue of GATT server is full.
错误描述
GATT服务端准备写入队列已满。
可能原因
GATT服务端准备写入队列已满，GATT客户端写入数据量过大。
处理步骤
GATT客户端写入数据量过大，建议将数据分片写入。
对端设备存在错误行为
错误信息
Operation failed. Remote device has an error.
错误描述
对端设备出现错误。
可能原因
对端设备存在错误行为。
处理步骤
保证对端设备使用正确，再尝试操作。
未注册电量服务监听
错误信息
Operation failed. Unregistered bas observer.
错误描述
调用方未注册电量服务监听。
可能原因
调用方未注册电量服务监听。
处理步骤
保证已正常注册电量服务监听，再尝试操作。
电量服务监听已达最大数量
错误信息
Operation failed. Bas observers exceeds the limit.
错误描述
电量服务监听已达最大数量。
可能原因
电量服务监听已达最大数量。
处理步骤
取消部分业务对电量服务的监听后再尝试注册监听操作。
电量服务请求忙碌
错误信息
Operation failed. Bas request busy.
错误描述
电量服务请求忙碌。
可能原因
电量服务请求忙碌。
处理步骤
等待电量服务处理完当前请求后再进行操作。
以下为BLE蓝牙业务返回错误码2900099时的常见问题案例。
调用setCharacteristicChangeNotification失败-server端未创建描述符写入监听
调用setCharacteristicChangeNotification返回错误码2900099时，根据以下场景进行排查。
server端未创建on('descriptorWrite')监听，client端setCharacteristicChangeNotification接口处于持续请求的阻塞状态。
可能原因
server端未创建on('descriptorWrite')监听，无法接收到client端发来的描述符请求。
处理步骤
server端创建on('descriptorWrite')监听。
调用setCharacteristicChangeNotification失败-server端未及时应答
server端接收到client端发来的描述符请求后，未及时调用sendResponse接口应答（检查日志是否返回OnSetNotifyCharacteristic关键字），client端setCharacteristicChangeNotification接口处于持续请求的阻塞状态。
典型日志信息
- bta gattc enqueue: already has a pending command
可能原因
server端在接收到client端发来的描述符请求后，没有及时调用sendResponse接口应答。
处理步骤
server端在接收到client端发来的描述符请求后，及时调用sendResponse接口向client返回数据。
调用setCharacteristicChangeNotification失败-前序异步接口调用未完成
调用setCharacteristicChangeNotification接口时，有其它异步接口调用未完成，导致setCharacteristicChangeNotification接口调用被阻塞。排查方式如下：
- 在接口回调中设置日志打印，查看接口调用的完整顺序流程。从创建对象实例到数据传输，BLE蓝牙client端接口调用顺序参考如下：
- 调用createGattClientDevice接口创建client实例。
- 创建BLE蓝牙连接状态监听、MTU变化监听、特征值变化监听等接口。
- 调用connect接口连接BLE蓝牙。
- 调用setBLEMtuSize接口协商MTU。
- 调用getServices接口获取server端支持的所有服务能力。
- 调用setCharacteristicChangeNotification接口设置server端特征值内容变更通知的能力。
- 调用writeCharacteristicValue接口向server端写入特征值数据。
- 排查系统日志输出。可在问题复现后生成hilog日志，查看日志中各接口调用开始/完成时，系统日志输出的时间点，从而判断是否出现了接口调用阻塞情况。如：setCharacteristicChangeNotification接口调用开始时，系统日志中会打印出关键字setCharacteristicChangeNotification；接口调用完成时，可通过setCharacteristicChangeNotification接口Callback回调中自定义的日志进行判断。
可能原因
在调用setCharacteristicChangeNotification接口前，一般会先调用setBLEMtuSize异步接口，与server端协商MTU数据传输大小，然后再调用getServices接口，获取server端的特征值服务列表。这些前序异步接口调用未完成，导致setCharacteristicChangeNotification接口调用被阻塞。
处理步骤
在setBLEMtuSize和getServices接口依次调用成功后，再调用setCharacteristicChangeNotification接口，设置接收server端特征值内容变更通知的能力。完整调用顺序请参考连接和传输数据开发指导。
调用writeCharacteristicValue失败-前序接口调用未完成
当上一个非监听类BLE蓝牙接口（setBLEMtuSize、getServices和setCharacteristicChangeNotification）回调还未返回时写入数据，出现2900099报错提示，导致写入数据失败。
可能原因
前序非监听类BLE蓝牙接口调用未完成。
处理步骤
保证在其它非监听类BLE接口回调触发完成后，再调用writeCharacteristicValue接口写入数据。
GATT设备重连后接口调用失败-gattClient对象未及时销毁
每次重连GATT设备时都会重新创建新的gattClient对象，建立一路新的GATT连接。每次连接关闭后未及时调用close接口销毁gattClient对象实例。
可能原因
gattClient对象实例未及时销毁，导致每次重连时重复多次调用setCharacteristicChangeNotification和getServices，出现busy现象，进而导致报错2900099。
处理步骤
每次连接关闭后，及时调用close接口销毁gattClient对象。
2900100 IPC传输失败
错误信息
IPC failed.
错误描述
IPC 数据传输失败。
可能原因
数据传入异常。
处理步骤
请检查传入数据。
2901000 禁止读操作
错误信息
Read forbidden.
错误描述
禁止读操作。
可能原因
无读操作权限。
处理步骤
检查是否有读操作权限。
2901001 禁止写操作
错误信息
Write forbidden.
错误描述
禁止写操作。
可能原因
无写操作权限。
处理步骤
检查是否有写操作权限。
2901003 GATT未连接
错误信息
The connection is not established.
错误描述
GATT未连接。
可能原因
GATT处于未连接的状态下执行操作，例如调用getServices和readCharacteristicValue。
处理步骤
确保GATT处于已连接的状态。
2901004 GATT传输拥塞
错误信息
The connection is congested.
错误描述
GATT处于拥塞状态。
可能原因
读写特征值或描述符过于频繁，导致底层数据传输拥塞，例如入参GattWriteType为WRITE_NO_RESPONSE的writeCharacteristicValue接口调用过于频繁可能导致拥塞。
处理步骤
降低读写操作频率，如果是WRITE_NO_RESPONSE类型的写数据操作，建议调用间隔控制在50ms以上。
2901005 GATT未加密
错误信息
The connection is not encrypted.
错误描述
GATT处于未加密的状态下，执行需要加密权限的特征值或描述符读写操作。此操作是否需要加密由server端特征值或描述符的权限指定。
可能原因
GATT加密权限不足。
处理步骤
检查GATT是否有加密权限。
2901006 GATT未认证
错误信息
The connection is not authenticated.
错误描述
GATT处于未认证的状态下，执行需要认证权限的特征值或描述符读写操作。此操作是否需要认证由server端特征值或描述符的权限指定。
可能原因
GATT认证权限不足。
处理步骤
检查与对端设备是否配对，是否有认证权限。
2901007 GATT未授权
错误信息
The connection is not authorized.
错误描述
GATT处于未授权的状态下，执行需要授权的特征值或描述符读写操作。此操作是否需要授权由server端特征值或描述符的权限指定。
可能原因
GATT未授权。
处理步骤
检查GATT是否已授权。
2901008 GATT服务不存在
错误信息
GATT service is not found.
错误描述
GATT服务不存在。在获取指定的GATT服务之前，该服务应当已经被添加。
可能原因
GATT服务尚未被添加。
处理步骤
先调用addService添加该服务。
2901054 IO传输失败
错误信息
IO error.
错误描述
IO传输失败。
可能原因
IO传输异常，造成失败。
处理步骤
请重试该操作。
2902050 开启扫描失败
错误信息
Failed to start scan as Ble scan is already started by the app.
错误描述
开启扫描失败。
可能原因
BLE扫描已被应用开启。
处理步骤
检查是否已经开启扫描。若已开启，请先调用停止扫描接口停止当前扫描后，再重新开启扫描。
2902054 广播报文超限
错误信息
The length of the advertising data exceeds the upper limit.
错误描述
广播报文超过最大长度。
可能原因
传统广播报文的最大长度为31字节，超过此长度将返回异常。当前，该长度限制仅适用于传统广播，不包括扩展广播。
处理步骤
检查广播报文是否超过最大长度限制。
2902055 广播标识符无效
错误信息
Invalid advertising id.
错误描述
广播标识符无效。
可能原因
传入的广播标识符应为startAdvertising接口返回的值，无效的广播标识符默认为0xFF。
处理步骤
检查传入的广播标识符是否为startAdvertising接口返回的有效标识符。
2903050 HID不在前台
错误信息
HID application is not in the foreground.
错误描述
注册HID设备能力的应用不在前台。
可能原因
当前注册HID设备能力的应用处于后台。
处理步骤
检查注册HID能力的应用是否处于前台。
2903051 HID已注册
错误信息
Another HID application has been registered.
错误描述
其他应用已经注册过HID设备能力。
可能原因
只允许一个应用注册HID设备能力。
处理步骤
检查是否已经有其他应用注册HID设备能力。
2903052 HID未注册
错误信息
HID application does not register.
错误描述
当前应用还没有注册HID设备能力。
可能原因
应用只有在注册HID设备能力之后才能和HID主机进行连接并进行数据交互。
处理步骤
检查当前应用注册HID设备能力是否成功。
2903053 HID未连接
错误信息
HID device is not connected.
错误描述
当前HID设备还没有连接HID主机。
可能原因
只有在连接完成之后HID设备才能和HID主机进行数据交互。
处理步骤
检查当前应用是否注册HID设备能力并连接HID主机成功。
