A number of users have experienced startup crashes when first installing Bermuda, where this has been due to their systems having thousands (sometimes hundreds of thousands) of stale bluetooth advertisements cached in the backend.

These seem to persist in their systems via the /config/.storage/bluetooth.remote_scanners json file which gets saved out by the bluetooth manager on exit. There is a particular custom integration which might be responsible for this at least in a few cases, but until I test and prove if that's the case I'd rather not name it in speculation, plus it's possible there are others, and/or it might have been due to a bug in core that was later resolved, hard to say at this time.

Ideally, Bermuda should guard itself (and therefore the system) from instability caused by unexpected input.

This issue is to track those efforts to guard against, and ideally to resolve those cases. Additionally, attempts to replicate the issue and raise bug reports with packages that might cause this are also welcomed/intended.

Workaround

If you experience a crash on first installing and starting up with Bermuda, this issue might be relevant. It is especially so if you have previously had another bluetooth-tracking custom integration installed (so not from core, but via HACS or manual installation) - even if you have since uninstalled it.

On your HA system, check to see if this file is present, and how big it is:

~ # ls -l /homeassistant/.storage/bluetooth.*
-rw-r--r--    1 root     root         31284 Nov  9 05:06 /homeassistant/.storage/bluetooth.passive_update_processor
-rw-r--r--    1 root     root         80568 Nov  7 14:34 /homeassistant/.storage/bluetooth.remote_scanners
~ #

The bluetooth.remote_scanners file is the one of interest here. In this example, it is about 80KB in size (80568 bytes). This is a normal size for a moderately "busy" standalone house in a non-urban area. If your file is more than 300,000 bytes then you probably have this issue.

Do not proceed unless you have verified that the above applies to your situation, or you are comfortable with what you're doing.

You can work around the problem and get your system booting again by doing this in exactly this order:

shut down Homeassistant
rename or delete the bluetooth.remote_scanners file
start Homeassistant
ensure that the integration that caused the issue is no longer installed
if you have only now removed the responsible integration, repeat the first three steps above again, as it may put a lot of records back into the file on the next shutdown.

How to rename the file:

You will need access to the command line on your Homeassistant machine. This example works for HAOS (the custom Homeasstant virtual machine) but your system might have a different install location or you might need to find out how to get to a command line. If you post to any of the HA community forums, explain your problem and link to this issue, someone will probably be able to help you.

From a standar HAOS command line:

~ # mv /homeassistant/.storage/bluetooth.remote_scanners /homeassistant/.storage/bluetooth.remote_scanners.bad

Copy/paste the results (or take a photo, whatever you need to do) so you can show someone what happened if you run into trouble.

This should solve the issue for you and HA (and Bermuda) should start up properly on future attempts.

Bermuda response Part I: Duck and cover

Bermuda should, before starting to process any advertisements:

Perform a len() on each scanner's discovered_devices list.
If the scanner presents more than, say 2000 entries:
- Avoid using that scanner's data, either by halting/aborting the init process, or by blacklisting that scanner to avoid ever processing its data
- Alert the user of the issue, ideally with a Repair that links to the current instructions to resolve (right now, this page)

Bermuda response Part II: Counter-ops

Repairs have the option to walk the user through solving an issue via a data flow. Bermuda could:

Raise the Repair as per above
Offer to the user to perform the repair by "flushing all cached bluetooth advertisements"
With permission:
- directly prune the bluetooth backend's advert cache
- remove the cache file
- trigger the bluetooth backend to save out the data

Other options

It's possible that raising a repair on identifying excess stale records, flushing the backend cache and potentially throttling the rogue integration should really be raised with core to be performed by the bt manager itself, rather than having Bermuda try and stomp around in there.

agittins / bermuda

Gracefully handle excessive advert caches #367

Workaround

Bermuda response Part I: Duck and cover

Bermuda response Part II: Counter-ops

Other options