12  Troubleshooting

This chapter summarizes symptoms you often run into in the hands-on and in real development, with causes and fixes.

12.1 Build and flash

Symptom Cause Fix
nimble/nimble_port.h: No such file or directory bt is missing from PRIV_REQUIRES in main/CMakeLists.txt, or BLE is disabled in sdkconfig Write PRIV_REQUIRES bt. Delete sdkconfig and regenerate it (Chapter 4)
Changes to sdkconfig.defaults don’t take effect A value is already written in sdkconfig Delete sdkconfig before building, or use idf.py menuconfig
ble_store_config_init not found (implicit declaration) Not declared in a public header Declare void ble_store_config_init(void); yourself
Flashing stops with Failed to connect Cannot enter download mode, or another app is using the port Close the serial monitor. Hold BOOT and press RESET (Chapter 1)
idf.py not found The environment is not activated source ~/.espressif/tools/activate_idf_v6.0.1.sh (adjust the path to your environment)
Lots of red squiggles in the VS Code editor, but the build passes Code completion (clangd / IntelliSense) can’t read build/compile_commands.json Build once, then restart the language server

12.2 Not found / can’t connect

Symptom Cause Fix
Doesn’t appear in scans Advertising hasn’t started Does advertising as … appear in the log? Check the return value of ble_gap_adv_set_fields() (BLE_HS_EMSGSIZE if over 31 bytes)
Never found again once disconnected Advertising is not restarted on disconnect start_advertising() on BLE_GAP_EVENT_DISCONNECT
Disconnects / can’t be found as soon as you move a little away The antenna is not attached to the XIAO ESP32C3 Attach the supplied antenna to the U.FL connector
An old name keeps being shown The phone/PC is caching the name Turn Bluetooth off and on. In nRF Connect, rescan
Doesn’t appear in the Web Bluetooth list No service UUID in the advertisement (Step 2), or the browser is unsupported Flash Step 3 or later. Use Chrome / Edge

12.3 Notify doesn’t arrive

Symptom Cause Fix
No Notify The client has not subscribed to the CCCD Press ↓↓↓ in nRF Connect. Does subscribe … notify=1 appear in the log?
Only command responses don’t arrive Not subscribed to the Command CCCD Also enable Notify on the characteristic that returns responses
rc=6 (BLE_HS_ENOMEM) appears Sending too fast; out of mbufs Lengthen the send period, bundle data (Chapter 6)
rc=7 (BLE_HS_ENOTCONN) Tried to send after disconnecting Check the connection handle before sending
Data longer than 20 bytes gets cut off MTU is still 23 Split it, or check the result of MTU negotiation (BLE_GAP_EVENT_MTU)

12.4 Pairing

Symptom Cause Fix
Asked for the passkey every time Not bonding, or bond information is not saved sm_bonding = 1, ble_store_config_init(), CONFIG_BT_NIMBLE_NVS_PERSIST=y
Disconnects right after connecting / encryption fails (enc change status≠0) Only one side has the bond information (e.g. the ESP32-C3 was erase-flashed) Also forget the device on the phone/PC, then reconnect
Can’t access even after entering the passkey (Insufficient Authentication) With this peer combination it became Just Works, giving an unauthenticated key Check authenticated=0 in the log. Check the peer’s IO Capability
No pairing dialog appears No protected characteristics, or no Security Request sent *_ENC / *_AUTHEN flags, ble_gap_security_initiate()
Notify arrives even though not paired The CCCD is not protected Add BLE_GATT_CHR_F_NOTIFY_INDICATE_ENC / _AUTHEN
Bonds are not saved from the 4th device on Storage is full (3 entries by default) store_status_cb = ble_store_util_status_rr, or increase CONFIG_BT_NIMBLE_MAX_BONDS
TipTo delete all bond information
  • ESP32-C3 side: idf.py -p PORT erase-flash (this erases the whole flash, including the app; flash again). From a program, ble_store_clear() also works
  • Phone side: in the OS’s Bluetooth settings, “Forget this device” for HANDSON-C3-XXXX
  • The basic rule is to delete on both sides together

12.5 Unstable behaviour

Symptom Cause Fix
task_wdt: Task watchdog got triggered Not waiting inside a loop, or doing long processing in a callback Add vTaskDelay(). Turn heavy processing into an event for another task
Resets with Stack overflow in task … Task stack too small Increase the stack size in xTaskCreate(). Make large arrays static
BLE responses suddenly become slow Waiting in a host task callback Callbacks only post (Chapter 10)
queue full, drop … appears Handler processing can’t keep up with event generation Make handlers faster. Lengthening the queue only treats the symptom

12.6 Reading logs

To see NimBLE’s own logs in detail, set idf.py menuconfig → Component config → Bluetooth → NimBLE Options → NimBLE Host log verbosity to Debug. It produces a large amount of ATT and SM traffic, so use it only when investigating a problem.

To see the BLE communication itself, a sniffer such as nRF52840 Dongle + nRF Sniffer for Bluetooth LE + Wireshark lets you observe advertising, connection and pairing packets (contents after encryption cannot be read without the keys).