Skip to main content

Common Issues

Use the guidance below to diagnose and resolve common issues.

1. Feature Calls Fail Immediately After Connection​

The BLE connection is established before the SDK finishes discovering services, opening its protocol channel, and loading the device state. Feature calls made during this interval may fail because the device is not ready.

Set the device delegate before connecting, then wait for deviceDidReady(...) or confirm that isConnectedAndReady is true before calling a feature. After reconnection, wait for the new ready event again.

2. A Feature Is Available in Code but Fails on Some Devices​

The SDK exposes a shared API surface across device models, but actual support can depend on the device model, firmware, capability flags, and supported-value collections.

Check the feature's support information before enabling it in the UI. If the device returns deviceNotSupport, treat the feature as unavailable for that device instead of retrying the same request.

3. The Hotspot Connects but the Feature Does Not Finish​

Media File Import, RTSP, and Camera OTA switch from Bluetooth control to a device-hosted Wi-Fi hotspot. Joining the hotspot is only an intermediate stage.

Keep the device, workflow owner, and callbacks alive until the final feature callback, and do not start another hotspot workflow at the same time. If the hotspot connection is lost, restart the complete workflow instead of reusing its previous URL. Required setup is documented in Installation.

4. AI Features Remain Unavailable After Device Connection​

Bluetooth connection and AI service authorization are separate states.

For a bundled provider, initialize AIBudsAISDK, configure the selected provider, and wait for the device authorization state. For an app-owned AI service, complete authentication in the host app and report the result through reportSelfAiServiceAuthResult; otherwise the device cannot know that the service is authorized. See Report Self-AI Authorization.

When You Still Need Help​

Use the Issue Report Template so the report includes the environment, device state, reproduction steps, error, and diagnostics needed for investigation.