= FAQ: I got a BleError. Now what?

Foreword

The library does try its best to allow you for the best debugging experience possible. Unfortunately Bluetooth Core Specification is ~2800 pages strong and it takes a very large effort to handle every potential situation gracefully. Unfortunately the developers of this library do not have enough time to help with every single case. Especially when the errors may be caused by this library or (more probable) by the firmware implementation of the peripheral you try to use.

Before creating issues like: Device disconnects when... or Function X always returns an error look into your own case and try to figure it out by yourself. How to do that the below instruction should help you. If you have doubts if the library does its job well then try to use some free apps for BLE interaction like nRF Connect (Android/iOS)

If you will find any way in which the library can be improved to better handle/report erroneous situations feel free to document it throughly and make an issue (or better!) create a Pull Request.

BleError

Usually getting the error message is not enough to diagnose the problem. Message is just to inform what went wrong. The BleError has more properties than only the message. Here is the declaration on what the error contains and how to interpret it.

Keep in mind that console.log(bleError) will only log the message. To get the full picture you can use console.log(JSON.stringify(bleError)).

All BLE operations are asynchronous. It may happen that you will get an error with message Characteristic X notify change failed for device Y and service Z which will be true but at the same time the cause of this error would be the peripheral being disconnected. You shall always monitor Device.onDisconnected(listener: (error: ?BleError, device: Device) => void): Subscription which will be called each time the Device gets disconnected — it is possible to check the cause of disconnection here.

Frequent errors

This section contains frequent mistakes made by newbies to the BLE and may be expanded in the future.

(Android) Scan cannot start but I have location permissions

Check if the Location Services (GPS/location switch under the top bar) is also turned on.

Service/Characteristic not found

BleError: Service X for device ? not found

Most probably the service you try to use is not available. Possible causes:

1. Device.discoverAllServicesAndCharacteristics() was not yet finished. This procedure should be used every time the Device is connected
2. A mistake in the Service UUID was made. You can perform Device.discoverAllServicesAndCharacteristics() and list all the discovered Characteristics from every Service and check what UUIDs are present.

Read/Write/Notification fails

Check if the Characteristic you try to interact with has the property to work this way. Not every characteristic is readable/writable/notfiable. To check the properties of all characteristics you can perform Device.discoverAllServicesAndCharacteristics() and go through all Service.characteristics().

(iOS) Notifications emit error but it works using different tools

BleError: Characteristic X notify change failed for device ? and service Z

Most probably the device you are using is not conforming to the Core Bluetooth Specification and the Characteristic you try to monitor does not have a Client Characteristic Configuration descriptor.