#3980·homebridge

Provide a supported way for plugins to reconcile restored cached accessories

Author: bwp91Created Jul 27, 2026Updated Aug 30, 2026
Labelsenhancement

Splitting this out of #3919, where @n0rt0nthec4t raised it and it risks getting lost inside a narrower question.

The gap

When Homebridge restores a cached accessory, the plugin gets back whatever shape was last published. If the plugin's expectations have since changed — a service is no longer wanted, a characteristic was dropped, a context field was added, or HAP itself changed between versions — the plugin is on its own in noticing and repairing that.

The tools to fix it exist (removeService, updatePlatformAccessories), so this is not about missing capability. It is that every plugin author ends up writing their own reconciliation pass, and each one discovers the same traps independently:

  • removing every service breaks, because AccessoryInformation is required
  • doing the work too early, during cache load, crashes deserialisation
  • the fallback that always works — delete the accessory and let it be recreated — costs the user their room assignment, name, and automations

In practice a lot of plugins skip it, and the symptom lands on users as a stale service that never goes away.

What might help

Roughly in order of how much they'd cost us:

  1. Document the pattern. The safe reconciliation recipe, in the plugin developer docs: remove the specific services you no longer want in your accessory handler, never AccessoryInformation, then call updatePlatformAccessories. This alone would cover most cases.
  2. A helper on PlatformAccessory — something like "keep exactly these services and drop the rest", so the common case is one call instead of a hand-rolled loop with a footgun in it.
  3. A validation hook before registration, so a plugin can inspect a restored accessory and say whether it is still usable, with a defined recovery path when it is not.
  4. Cache sanity checking in core, for the cases where the stored data is incompatible with the current HAP version rather than with the plugin.

Opening this for discussion rather than proposing we build all of it. My own view is that 1 is worth doing regardless and 2 is a small, contained addition; 3 and 4 are a much bigger commitment and want a clearer picture of how often incompatible caches actually occur.