Integration Watchdog

Features

• Automatic check at a set interval (5 minutes by default) of every loaded integration
• Reload of an integration once all its enabled entities have been unavailable for the grace period (15 minutes by default)
• Never during startup: nothing is reloaded while Home Assistant starts or stops, nor during the grace period after it has started
• No reload loop: an integration that stays unavailable is reloaded at most 3 times in a row (configurable), the delay between two reloads doubling each time; then the watchdog gives up on it until it recovers. The counts are saved, so a restart doesn't start over
• Notification for each reload, failed reload and give-up: persistent notification, and optionally your notify actions (mobile app…)
• Repairs issue for each integration given up, removed once it recovers, with Try again to start over and reload it now
• Diagnostics with personal data redacted
• Ignored integrations, chosen in the integration options among those set up, or typed as a domain, and ignored entries: one entry of an integration (a camera of several) left alone while its other entries are still watched
• Power cycles: associate a device with the smart plug that powers it; once all the device's entities have been unavailable for its own delay, the plug is switched off then on again, with the same safeguards as the reloads (limit, doubling delay, pause, nothing during startup)
• Pause entity: while an entity of your choice is on (an input_boolean for maintenance, a schedule for the night), nothing is reloaded; the checks still list what is unavailable
• Reloads in 24 h sensor: how many reloads the last day, per integration — an unstable integration shows up there
• Check now button and integration_watchdog.check action; integration_watchdog.reset action to start over on an integration
• Unavailable integrations sensor with the list, Last reload sensor, Last check sensor
• integration_watchdog_reloaded event for each reload, to notify or log
• Sidebar panel (administrators), in three tabs: the status with the whole history, the power cycles (add, remove, see their state) and every setting
• Lovelace card bundled with the integration: overall status, unavailable integrations and the recent reloads (kept across restarts)
• Mini card: the status and the unavailable integrations on two lines, with a detail button showing the full card
• One failing reload doesn't stop the others; two checks never run at the same time
• English, French, German, Spanish, Italian, Dutch, European Portuguese, Polish, Serbian (Cyrillic and Latin), Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek; pt-BR uses the European Portuguese texts

Prerequisites

• Home Assistant 2024.12 or newer
• Nothing else: the watchdog only uses Home Assistant's own registries and the integrations' Reload, and its card is installed with it. The System Monitor Card can also show its sensors on a dashboard

Configuration

Settings → Devices & services → Add integration → Integration Watchdog. Change the options later with the Configure button.

Configure opens a menu: Settings (the options above), Add a power cycle and Remove power cycles. Everything can also be changed from the sidebar panel.

Sidebar panel#

Integration Watchdog in the sidebar, for administrators only, has three tabs under its toolbar (the tab is in the address, /integration-watchdog/settings):

• Status: drawn by the panel itself, at once — a summary (unavailable and given-up integrations, last check with Check now, reloads since start, ignored integrations), the unavailable integrations (since when, reloads, Try again on one given up) and the last 50 reloads and power cycles side by side on a wide screen, one under the other on a phone; each line opens its integration
• Power cycles: each device with its plug and delays, whether it is available, unavailable or given up, a warning when its plug is off or unavailable, a link to the device and Remove; below, the form to add one (the devices already cycled and the plugs of the chosen device are not offered)
• Settings: every option of Configure → Settings, saved at once

The labels are the options flow's own, in the language of Home Assistant. Saving reloads the integration once; a field you have not edited follows a change made elsewhere (Configure, another administrator). Behind the panel are four admin-only WebSocket commands: integration_watchdog/settings, integration_watchdog/update_settings, integration_watchdog/add_power_cycle and integration_watchdog/remove_power_cycle. To hide the entry, long-press the sidebar title and hide Integration Watchdog, like any other panel.

Power cycles#

A device that hangs (a router, a hub, a camera) often only comes back once its power is cut. Associate it with the smart plug that powers it, in Configure → Add a power cycle:

The plug is only switched off when it is on: a plug you switched off on purpose, or that is unavailable itself, is left alone. Power cycles follow the reload rules: none while Home Assistant starts or during the grace period after it has started, none while the pause entity is on, at most Reloads in a row in a row with a delay that doubles each time (10, 10, then 20 minutes…), then the watchdog gives up on the device until one of its entities has been available again for the current delay. Each power cycle, failed power cycle and give-up is notified (one persistent notification per device), recorded in the history shown by the card, and fires the integration_watchdog_power_cycled event.

The plug is always switched on again, even when switching it off failed. If Home Assistant stops while it is off, it is switched on at the first check after the next start. The integration of the device is still watched as usual: if all its entities are unavailable too, it is also reloaded after its grace period.

What counts as unavailable#

An integration (config entry) is reloaded when:

• it is loaded, or its setup failed (setup_retry, setup_error): a reload retries it right away instead of waiting for Home Assistant's next retry. Disabled integrations are left alone
• it is not ignored, and it is not a helper (template, group, utility meter, derivative…): their entities follow their sources, so reloading them can't fix anything
• it has at least one enabled entity, and every enabled entity is unavailable
• the most recent of these entities has been unavailable for at least the grace period
• Home Assistant has been running for at least the grace period

Disabled entities are left out. Entities the integration didn't create, for example because the device was off or unreachable when it loaded (shown as "not provided" in Home Assistant), count as unavailable. An integration with a single entity still available is not reloaded.

The check is per integration entry, not per device: an entry with one device down and another one working is left alone.

Limiting reloads#

An integration that stays unavailable after a reload is reloaded again after the grace period, then after twice the grace period, and so on, up to the Reloads in a row option. With the defaults: after 15 minutes, then 15 minutes later, then 30 minutes later. If it is still unavailable once the delay after the last one has passed (60 minutes with the defaults), the watchdog gives up on it, sends a notification, and doesn't touch it again until one of its entities has been available for the current delay, counted from its return. An integration that comes back for a moment and falls again keeps its count. Leaving the list is not a recovery: an integration whose setup or unload is still in progress (a reload that went past its timeout), or that has no enabled entity with a state keeps its count until one of its entities is actually available. Disabling an integration resets its count right away, even if you enable it again a few seconds later: once enabled again, it starts over.

A reload that doesn't finish within 5 minutes, or a notify action that doesn't answer within 30 seconds, counts as failed, so that a hung integration can't block the following checks.

The count is saved with the history (.storage/integration_watchdog.history): after a restart of Home Assistant, an integration given up stays so, and one being reloaded keeps its count and delay. Entries removed while Home Assistant was stopped are dropped when it starts. Changing the options keeps the count too, so an integration given up stays so (until a higher Reloads in a row allows more reloads). To start over on an integration, use Try again on its Repairs issue, the integration_watchdog.reset action or the card's Try again button.

Notifications#

Each reload, failed reload and give-up creates a persistent notification, one per integration (the next one replaces it), in the language of Home Assistant. It is dismissed once the watchdog starts over for the integration (recovered, reset, disabled or removed), and when Integration Watchdog is removed. The same title and message are sent to the notify actions chosen in the options.

Repairs#

Giving up on an integration also raises an issue in Settings → System → Repairs, one per integration. It goes away by itself once the integration has recovered (available again for its current delay), is disabled or removed, or gets more reloads after Reloads in a row was raised. An integration still given up when Home Assistant restarts gets its issue back.

Opening the issue offers Try again: submitting it forgets the reloads of the integration, deletes the issue and reloads the integration now (like the integration_watchdog.reset action). The reload runs in the background: the dialog closes at once, saying that it was started, and a failed reload is logged. If it is still unavailable afterwards, the watchdog starts over: reloads up to Reloads in a row, then gives up again.

Diagnostics#

Settings → Devices & services → Integration Watchdog → ⋮ → Download diagnostics gives the options and the watchdog's state: unavailable integrations, reload counts per entry, last reload and history. Integration titles (often an e-mail address or a host) and notify actions are redacted; domains and entry ids are kept.

Entities#

Action integration_watchdog.check#

Runs a check now and waits for the reloads. If a check is already running, waits for it to end, then runs its own. For administrators. Does nothing while Home Assistant is starting.

action: integration_watchdog.check

Action integration_watchdog.reset#

Starts over for one integration entry: forgets its reloads (given up or not), deletes its Repairs issue and reloads it now. Waits for a check still running. Fails if the entry doesn't exist or the reload fails (the count is reset anyway). For administrators.

action: integration_watchdog.reset
data:
  entry_id: 01JABCDEF0123456789ABCDEFG

Event integration_watchdog_reloaded#

Log each reload in the logbook:

triggers:
  - trigger: event
    event_type: integration_watchdog_reloaded
actions:
  - action: logbook.log
    data:
      name: Integration Watchdog
      message: >
        reloaded {{ trigger.event.data.title }} ({{ trigger.event.data.domain }}),
        attempt {{ trigger.event.data.attempt }}/{{ trigger.event.data.max_reloads }}

Event integration_watchdog_power_cycled#

Card

The integration serves the Integration Watchdog Card and adds it to the dashboard resources (or loads it on every page when the resources are managed in YAML): no separate install. Add it from the card picker, or:

type: custom:integration-watchdog-card

• Header: status (all available, n unavailable, n given up, checking…), time of the last check and the Check now button. On a narrow card the status takes a second line, shortens, then keeps only its coloured dot, with the text on hover. In a Sections view the card takes at least 8 columns
• Summary: unavailable integrations, reloads since Home Assistant started, ignored integrations (listed on hover)
• Unavailable integrations: for each one, how long it has been down and its reloads (1/3 reloads), Grace period before the first one, Given up once the limit is reached
• Recent reloads: the last attempt of each integration (reloaded, failed or given up), newest first, with the attempt and how long ago. The history is saved, so it survives a restart
• For an administrator, a row opens the integration's page in Settings on its entry (/config/integrations/integration/<domain>#config_entry=<entry_id>), to reload it by hand or read its logs (other users can't open Settings, so their rows are not clickable). Integration logos come from the Home Assistant brands
• For an administrator, an integration given up gets a Try again button next to its row: it runs the integration_watchdog.reset action (start over and reload now)

Every option is in the visual editor:

Mini card#

custom:integration-watchdog-mini-card shows the essentials on two lines, for a compact dashboard: the icon, title, Check now button and status, then a chip per unavailable integration (Hue Bridge · 1/3 reloads, Zigbee · Given up), or the last reload while everything is available, and the time of the last check. Search for Integration Watchdog Mini Card when adding a card, or in YAML:

type: custom:integration-watchdog-mini-card

• The detail button (top right) switches the card to the full card, with the same options, and back, as does a click anywhere else on the page
• For an administrator, an integration's chip opens its page in Settings, on its entry; for other users, a chip opens the sensor
• In a Sections view the card takes 6 columns by default, its minimum; on a narrow card the icon gives way and the status keeps only its coloured dot

It takes every option of the full card (they set its detail view, hide_when_ok and check_button apply to both views), plus:

The System Monitor Card can also show the watchdog's sensors next to the rest of the system.

How it works

At each interval, the integration goes through the config entries, reads the states of their entities from the entity registry, and reloads the qualifying entries one at a time, as the Reload menu of the integration does. No check runs before Home Assistant has fully started; the first check runs right after, and only lists the unavailable integrations until the grace period has passed.

To debug:

logger:
  logs:
    custom_components.integration_watchdog: debug

Support

If you find this project useful, you can support its development:

Deprecated

• Integration Watchdog is now a module of System Hub, and this repository is archived: no more updates here. Turned on in System Hub, the module takes over the settings of Integration Watchdog. While both are set up, Integration Watchdog raises a repair in Settings → Repairs, as it would otherwise run twice and register its cards twice: remove Integration Watchdog and its card resource once the module is on. See Migrating (juju35/ha-system-hub#49, thanks @FredM67).

Improvements

• Panel, Status tab: drawn by the panel itself instead of embedding the card, so it shows at the first opening. A summary (unavailable and given-up integrations, last check with Check now, reloads since start, ignored integrations), the unavailable integrations (since when, reloads, Try again on one given up) and the last 50 reloads and power cycles, side by side on a wide screen and one under the other on a phone. Each line opens its integration.
• Panel shown at once: the release keeps its languages in the panel file instead of a separate file to wait for.

Fixes

• Panel empty on its first opening (fine when coming back to it): in the release, the panel is only defined once the page's language file has loaded, and Home Assistant had already handed it the connection, the address and the layout by then; they were lost and nothing was drawn. They are now taken up when the panel is defined.

Improvements

• Panel, Power cycles tab: device and plug pickers you can search. The two long drop-down lists are replaced by a search field over a short scrolling list grouped by area (accents and case ignored, every word must match the name, area, integration or entity ID). Arrow keys and Enter choose, Escape clears the search; the choice shows with its area and a Change button, and the focus moves on to the plug, then the delay. The plugs in the chosen device's area are listed first, outlets before the other switches. At most 50 rows are shown: type to narrow down the rest.
• Fewer plugs offered: configuration and diagnostic switches (child lock, LED, an integration's options) are no longer offered as a power plug.

Performance

• Panel opens faster: the settings and the form labels load alongside the card instead of after it (the card's bundle and language file could delay them by a few seconds).

Features

• Power cycles: associate a device with the smart plug that powers it (Configure → Add a power cycle: device, plug, Unavailable for in minutes, Off for in seconds). Once all the device's enabled entities have been unavailable for that delay, the plug is switched off, then on again. Only when the plug is on (one switched off on purpose or unavailable is left alone), never during startup or the grace period after it, nor while the pause entity is on; at most Reloads in a row in a row, the delay doubling each time, then given up until the device recovers. Each power cycle, failure and give-up is notified, shown in the card's history with the plug used, and fires the integration_watchdog_power_cycled event. The plug is always switched on again, also after a restart of Home Assistant during the power cycle.
• Configure now opens a menu: Settings, Add a power cycle, Remove power cycles.
• Sidebar panel (administrators only), with tabs under its toolbar as in Smart Comfort: Status (the card with the whole history), Power cycles (list with their state, add, remove) and Settings (every option). The tab is in the address; the form labels are the options flow's translations, the panel's own texts in the 22 languages.