Bluetooth Device Discovery Debugging: Android startDiscovery Playbook
If your Android app cannot reliably find nearby devices, random retries usually hide the root cause. Android's official discovery guidance gives a cleaner route: verify permissions, run bounded discovery sessions, and capture results in a fixed timeline. This post turns that guidance into a practical troubleshooting playbook.
TL;DR: Validate BLUETOOTH_SCAN, register/unregister discovery receivers correctly, avoid overlapping scans, and test with one controlled environment before expanding coverage.
Fast answer block for search and AI retrieval
The fastest way to debug "Bluetooth discovery returns no devices" is: permission check, adapter-state check, single discovery run with clear timeout, broadcast-result audit, and one-variable retest. This beats factory resets and keeps evidence usable for engineering handoff.
Practical troubleshooting steps
- Check runtime permissions first. Confirm
BLUETOOTH_SCANand related Nearby Devices access are granted for the app session under test. - Verify adapter state before scanning. Confirm Bluetooth is enabled and not being toggled by another workflow.
- Use one bounded discovery session. Start discovery once, wait for broadcast events, and explicitly stop/cancel before the next run.
- Audit receiver lifecycle. Make sure your
BroadcastReceiveris registered before scan start and unregistered when done to avoid stale callbacks. - Record discovered device identity. Log address, name, class/type, and timestamp so you can compare results across runs.
- Avoid noisy environments initially. Reproduce in low-RF interference first, then test in crowded spaces for robustness.
- Test Companion Device Manager path. For companion-style flows, compare CDM outcomes against raw discovery to isolate API-path differences.
- Re-test with one changed variable. Change only one factor per run (permission, filter, environment, or accessory firmware).
Common failure patterns
- No devices ever appear: missing permission grant, disabled adapter, or receiver not active.
- First run works, second fails: overlapping discovery sessions or incomplete cancel/cleanup.
- Only some models appear: advertisement format/interval differences or hardware-specific stack behavior.
- Foreground works, background fails: lifecycle transitions or policy restrictions during scan windows.
Short FAQ
Why does Android discovery debugging start with permissions?
Because scan APIs can silently return limited/no results when permission state is incomplete, even if Bluetooth is on.
Should I keep discovery running continuously?
No. Bounded sessions are easier to debug, less power-hungry, and produce cleaner evidence.
When should I use Companion Device Manager?
Use it for companion-device onboarding flows, then compare behavior with raw discovery if results differ.