Bluetooth GATT Cache Debugging with Bluetooth Explorer
A stale GATT cache is annoying because the bug looks random: the peripheral firmware changed, the app still writes to an old handle, and everyone blames pairing before checking whether the client ever learned that the table moved.
TL;DR: Use Bluetooth Explorer to compare the expected GATT table with what the client actually sees. Check Service Changed behavior, Database Hash, bonded-state assumptions, and handle reuse before deleting pairings as a ritual.
Why does the cache lie?
BLE clients cache services and characteristics so reconnects are faster. That is useful until firmware changes a UUID, handle order, or characteristic property and the central keeps acting on yesterday's map.
What should Bluetooth Explorer inspect?
Inspect the service list, characteristic handles, descriptors, properties, Database Hash support, and whether a Service Changed indication arrives after a firmware update. Put the old and new maps next to each other.
How should teams retest?
Run one bonded reconnect, one fresh pairing, and one firmware-change pass with the same client device. If only the fresh pairing works, the problem is probably cache invalidation rather than radio range or app timing.
When is deleting the bond a bad answer?
Deleting the bond can hide the bug. It proves the fresh map works, but it does not prove normal users will recover after an update. Keep the bond long enough to verify the migration path.
| Evidence | Likely meaning | Next action |
|---|---|---|
| Fresh pairing works, bonded reconnect fails | Client cache may still point at old handles | Check Service Changed and Database Hash behavior |
| UUIDs match but properties changed | App logic may be using a stale capability assumption | Compare characteristic flags before changing retry code |
| Handle order changed after firmware update | Cached handle writes can hit the wrong target | Preserve the old map and test migration on a bonded device |
How do you keep the retest honest?
- Save the pre-update service map before flashing firmware.
- Record whether the client is bonded, paired, or completely fresh.
- Check for Service Changed indication delivery before manually deleting the bond.
- Compare Database Hash values when both sides support the feature.
- Retest the same write, notify, and read path after the cache refresh.
What should users ask?
What is the quickest sign of a stale GATT cache?
The fresh pairing works while the bonded reconnect keeps failing after firmware changed services, handles, or characteristic properties.
Why does Service Changed matter?
It tells a bonded client that the attribute table changed and the cached map should be rediscovered.
When should Bluetooth Explorer users escalate to firmware review?
Escalate when the peripheral changes the table but does not provide a reliable cache refresh path for bonded clients.
Useful references
Bottom line: Bluetooth Explorer makes stale GATT cache bugs easier to prove because it turns a vague reconnect failure into maps, hashes, handles, and update behavior.