If this application has never started a scan, you can turn Bluetooth off and then back on to release the scanning resources occupied by other applications.
If this application has already started a scan on another channel, you can call the stopScan API to halt the scan. After the hardware resources are released, restart the current scan.

[h2]GATT Disconnected

Error Message

Operation failed. GATT not in connected state.

Description

The GATT is not connected.

Possible Causes

This error code is reported if the GATT connection is not established.

Solution

Connect to the GATT and try again.

[h2]Connections are not allowed during service scanning.

Error Message

Operation failed. Not allowed to connect during scanning.

Description

Connections are not allowed during scanning.

Possible Causes

Connections are not allowed during service scanning.

Solution

Complete the service scanning before initiating a connection.

[h2]Invalid Bluetooth address or transmission type.

Error Message

Operation failed. Invalid bluetooth addr or transport type.

Description

Invalid Bluetooth address or transmission type.

Possible Causes

The input parameter contains an invalid Bluetooth address or transmission type.

Solution

Check whether the input parameters meet the protocol requirements.

[h2]IPC data transfer failed.

Error Message

Operation failed. IPC trans failed.

Description

IPC data transfer failed.

Possible Causes

Data transfer is abnormal.

Solution

Check the input data and try again.

[h2]The number of connections has reached the maximum.

Error Message

Operation failed. Max connections has reached.

Description

The maximum number of connections has been reached.

Possible Causes

The maximum number of connections has been reached.

Solution

Clear the connected devices and try again.

[h2]The device is connected.

Error Message

Operation failed. This device has connected.

Description

The device is connected.

Possible Causes

The device is connected.

Solution

The device is connected. Do not perform the operation repeatedly.

[h2]Device Not Connected

Error Message

Operation failed. This device isn't connected.

Description

The device is not connected.

Possible Causes

The device is not connected.

Solution

The device is not connected. The current operation is invalid. Connect the device first.

[h2]The queue for the GATT server to prepare data to be written is full.

Error Message

Operation failed. The prepare write queue of GATT server is full.

Description

The queue for the GATT server to prepare data to be written is full.

Possible Causes

The queue for the GATT server to prepare data to be written is full, and the amount of data written by the GATT client is too large.

Solution

If a large amount of data is written to the GATT client, fragment the data before writing it.

[h2]Peer Device Error

Error Message

Operation failed. Remote device has an error.

Description

An error occurs on the peer device.

Possible Causes

The peer device has an error.

Solution

Ensure that the peer device is used correctly and try again.

[h2]Battery service listener not registered.

Error Message

Operation failed. Unregistered bas observer.

Description

The caller has not registered a battery service listener.

Possible Causes

The caller has not registered a battery service listener.

Solution

Ensure that the battery service listener has been registered properly, and try again.

[h2]Max number of battery service listeners reached.

Error Message

Operation failed. Bas observers exceeds the limit.

Description

The number of battery service listeners has reached the maximum.

Possible Causes

The number of battery service listeners has reached the maximum.

Solution

Cancel the listening of some services on the battery service and try to register the listener again.

[h2]Battery service request busy.

Error Message

Operation failed. Bas request busy.

Description

The battery service request is busy.

Possible Causes

The battery service request is busy.

Solution

Wait until the battery service processes the current request and then perform the operation again.

The following are common cases when the BLE service returns error code 2900099.

[h2]Failed to Call setCharacteristicChangeNotification – No Descriptor Write Listener Created on the Server

If error code 2900099 is returned when setCharacteristicChangeNotification is called, troubleshoot the issue based on the following scenarios:

The server does not create the on('descriptorWrite') listener, and the setCharacteristicChangeNotification API on the client is blocked by continuous requests.

Possible Causes

The server does not create the on('descriptorWrite') listener and cannot receive the descriptor request from the client.

Solution

Create an on('descriptorWrite') listener on the server.

[h2]Failed to Call setCharacteristicChangeNotification – Server Does Not Respond in Time

After receiving the descriptor request from the client, the server does not call the sendResponse API in a timely manner (check whether the log contains the keyword OnSetNotifyCharacteristic). The setCharacteristicChangeNotification API on the client is blocked due to continuous requests.

Typical log information

bta gattc enqueue: already has a pending command

Possible Causes

After receiving the descriptor request from the client, the server does not call the sendResponse API in a timely manner.

Solution

After receiving the descriptor request from the client, the server calls the sendResponse API to return data to the client in a timely manner.

[h2]Failed to Call setCharacteristicChangeNotification – Previous Asynchronous API Call Not Completed

When the setCharacteristicChangeNotification API is called, another asynchronous API is being called. As a result, the setCharacteristicChangeNotification API call is blocked. The troubleshooting method is as follows:

Set log printing in the API callback to view the complete sequence of API calls. The sequence of calling APIs on the BLE client from object instance creation to data transmission is as follows:
- Call createGattClientDevice to create a client instance.
- Create APIs for listening to the BLE connection status, MTU changes, and characteristic value changes.
- Call connect to connect to the BLE device.
- Call setBLEMtuSize to negotiate the MTU.
- Call getServices to obtain all service capabilities supported by the server.
- Call setCharacteristicChangeNotification to set the capability of notifying the server of characteristic value changes.
- Call the writeCharacteristicValue API to write characteristic data to the server.
Check the system logs. After the problem is reproduced, hilog logs are generated. You can check the time points when the system logs are generated when the calling of each API starts or ends to determine whether the API calling is blocked. For example, when the setCharacteristicChangeNotification API is called, the keyword setCharacteristicChangeNotification is printed in the system logs. When the API call is complete, you can check the custom logs in the callback of the setCharacteristicChangeNotification API.

Possible Causes

Before calling the setCharacteristicChangeNotification API, the setBLEMTUSize asynchronous API is usually called to negotiate the MTU data transmission size with the server, and then the getServices API is called to obtain the characteristic value service list from the server. The asynchronous API calls are not complete, causing the setCharacteristicChangeNotification API call to be blocked.

Solution

After the setBLEMtuSize and getServices APIs are successfully called in sequence, call the setCharacteristicChangeNotification API to set the capability of receiving notifications about characteristic changes on the server. For details about the complete API call sequence, see GATT-based Connection and Data Transmission.

[h2]Failed to Call writeCharacteristicValue – Previous API Call Not Completed

When data is written before the callback of the previous non-listening BLE API (setBLEMtuSize, getServices, or setCharacteristicChangeNotification) is returned, error code 2900099 is reported, indicating that data writing fails.

Possible Causes

The previous non-listening BLE API is not completely called.

Solution

Ensure that writeCharacteristicValue is called to write data only after the callback of other non-listening BLE APIs is triggered.

[h2]API Calling Failure After GATT Device Reconnection – gattClient Object Not Destroyed in a Timely Manner

Each time the GATT device is reconnected, a new gattClient object is created to establish a new GATT connection. The close API is not called in a timely manner to destroy the gattClient object instance after each connection is closed.

Possible Causes

The gattClient object instance is not destroyed in a timely manner. As a result, setCharacteristicChangeNotification and getServices are repeatedly called during each reconnection, causing the system to be busy and error 2900099 to be reported.

Solution

After each connection is closed, call the close API to destroy the gattClient object in a timely manner.

2900100 IPC Transmission Failure

Error Message

IPC failed.

Description

IPC data transmission fails.

Possible Causes

The input data is incorrect.

Solution

Check the input data.

2901000 Read Operation Forbidden

Error Message

Read forbidden.

Description

The read operation is not allowed.

Possible Causes

The caller does not have the read permission.

Solution

Check whether the caller has the read permission.

2901001 Write Operation Forbidden

Error Message

Write forbidden.

Description

The write operation is not allowed.

Possible Causes

The caller does not have the write permission.

Solution

Check whether the caller has the write permission.

2901003 GATT Disconnected

Error Message

The connection is not established.

Description

This error code is reported if the GATT connection is not established.

Possible Causes

An API call is invoked when the GATT connection is not established, for example, getServices or readCharacteristicValue is called.

Solution

Ensure that the GATT connection is established.

2901004 GATT Connection Congested

Error Message

The connection is congested.

Description

This error code is reported if the GATT connection is congested.

Possible Causes

Characteristic or descriptor read and write operations are performed frequently, causing congestion in underlying data transmission. For example, if the writeCharacteristicValue API is frequently called with GattWriteType being set as WRITE_NO_RESPONSE, congestion may occur.

Solution

Reduce the frequency of read and write operations. If GattWriteType is set to WRITE_NO_RESPONSE, the recommended interval is greater than 50 ms.

2901005 GATT Not Encrypted

Error Message

The connection is not encrypted.

Description

This error code is reported if characteristic or descriptor read and write operations requiring the encryption permission is performed when the GATT connection is not encrypted. Whether encryption is required for the operation is subject to the permission of the characteristic or descriptor on the server.

Possible Causes

The GATT encryption permission is not available.

Solution

Check whether the encryption permission is available for the GATT connection.

2901006 GATT Unauthenticated

Error Message

The connection is not authenticated.

Description

This error code is reported if characteristic or descriptor read and write operations requiring authentication is performed when the GATT connection is not authenticated. Whether authentication is required for the operation is subject to the permission of the characteristic or descriptor on the server.

Possible Causes

The GATT connection is not authenticated.

Solution

Check whether the device is paired with the peer device and whether the GATT connection is authenticated.

2901007 GATT Unauthorized

Error Message

The connection is not authorized.

Description

This error code is reported if characteristic or descriptor read and write operations requiring authorization is performed when the GATT connection is not authorized. Whether authorization is required for the operation is subject to the permission of the characteristic or descriptor on the server.

Possible Causes

The GATT connection is not authorized.

Solution

Check whether the GATT connection is authorized.

2901008 GATT Service Not Found

Error Message

GATT service is not found.

Description

The GATT service does not exist. Before obtaining the specified GATT service, ensure that the service has been added.

Possible Causes

The GATT service has not been added.

Solution

Call addService to add the service.

2901054 I/O Transmission Failure

Error Message

IO error.

Description

The I/O operation failed.

Possible Causes

The I/O transmission is abnormal.

Solution

Perform this operation again.

2902050 Failed to Enable Scanning

Error Message

Failed to start scan as Ble scan is already started by the app.

Description

This error code is reported if the attempt to enable scanning fails.

Possible Causes

BLE scanning has been enabled by the app.

Solution

Check whether scanning is enabled. If so, call the API for stopping scanning to stop the current scanning, and then enable scanning again.

2902054 Advertising Data Length Exceeds the Upper Limit

Error Message

The length of the advertising data exceeds the upper limit.

Description

This error code is reported if the length of the advertising data exceeds the upper limit.

Possible Causes

The maximum length of traditional advertising packets is 31 bytes. If the maximum length is exceeded, an exception is returned. Currently, this length limit applies only to traditional advertising but not extended advertising.

Solution

Check whether the length of the advertising packet exceeds the upper limit.

2902055 Invalid Advertising ID

Error Message

Invalid advertising id.

Description

This error code is reported if the advertising ID is invalid.

Possible Causes

The input advertising ID must be the value returned by startAdvertising. The invalid advertising ID is 0xFF by default.

Solution

Check whether the input advertising ID is a valid advertising ID returned by startAdvertising.

2903050 HID Is Not in the Foreground

Error Message

HID application is not in the foreground.

Description

The application that registers the HID device is not in the foreground.

Possible Causes

The application that registers the HID device is in the background.

Solution

Check whether the application that registers the HID device is in the foreground.

2903051 HID Has Been Registered

Error Message

Another HID application has been registered.

Description

The HID device has been registered by another application.

Possible Causes

Only one application can register the HID device.

Solution

Check whether the HID device has been registered by another application.

2903052 HID Not Registered

Error Message

HID application does not register.

Description

The application has not registered the HID device.

Possible Causes

An application can connect to and exchange data with the HID host only after registering the HID device.

Solution

Check whether the application successfully registers the HID device.

2903053 HID Not Connected

Error Message

HID device is not connected.

Description

The HID device has not connected to the HID host.

Possible Causes

The HID device can exchange data with the HID host only after the connection is successful.

Solution

Check whether the application successfully registers the HID device and connects to the HID host.

目录

Bluetooth Error Codes

2900001 Bluetooth Service Stopped

2900003 Bluetooth Disabled

2900004 Profile Not Supported

2900005 Bluetooth Device Not Connected

2900006 Maximum Number of Connections Reached

2900007 Asynchronous API Call Timeout

2900008 Null Pointer

2900009 Insufficient Hardware Resources

2900010 Resource Usage Reaches the Upper Limit

2900011 Frequent Operations

2900013 Preparation Timeout

2900014 User Rejects the Operation

2900015 Parameter Format Inconsistent with Specifications

2900016 Device Not Paired

2900099 Operation Failed

[h2]Operation Failure

[h2]Invalid Parameter

[h2]GATT Characteristic Value Is Empty

[h2]The previous API call is not complete when the current API is called.

[h2]The peer device is not discovered or recorded.

[h2]Bluetooth has been enabled.

[h2]The Bluetooth switch status is being switched.

[h2]Bluetooth is in the restricted state.

[h2]Cloud device is being linked.

[h2]The device is in the discovery process or has been discovered.

[h2]Failed to start scanning due to insufficient hardware resources.

[h2]GATT Disconnected

[h2]Connections are not allowed during service scanning.

[h2]Invalid Bluetooth address or transmission type.

[h2]IPC data transfer failed.

[h2]The number of connections has reached the maximum.

[h2]The device is connected.

[h2]Device Not Connected

[h2]The queue for the GATT server to prepare data to be written is full.

[h2]Peer Device Error

[h2]Battery service listener not registered.

[h2]Max number of battery service listeners reached.

[h2]Battery service request busy.

[h2]Failed to Call setCharacteristicChangeNotification – No Descriptor Write Listener Created on the Server

[h2]Failed to Call setCharacteristicChangeNotification – Server Does Not Respond in Time

[h2]Failed to Call setCharacteristicChangeNotification – Previous Asynchronous API Call Not Completed

[h2]Failed to Call writeCharacteristicValue – Previous API Call Not Completed

[h2]API Calling Failure After GATT Device Reconnection – gattClient Object Not Destroyed in a Timely Manner

2900100 IPC Transmission Failure

2901000 Read Operation Forbidden

2901001 Write Operation Forbidden

2901003 GATT Disconnected

2901004 GATT Connection Congested

2901005 GATT Not Encrypted

2901006 GATT Unauthenticated

2901007 GATT Unauthorized

2901008 GATT Service Not Found

2901054 I/O Transmission Failure

2902050 Failed to Enable Scanning

2902054 Advertising Data Length Exceeds the Upper Limit

2902055 Invalid Advertising ID

2903050 HID Is Not in the Foreground

2903051 HID Has Been Registered

2903052 HID Not Registered

2903053 HID Not Connected