Skip to main content

Repairs

Home Assistant keeps track of issues which should be brought to the user's attention. These issues can be created by integrations or by Home Assistant itself. Issues can either be fixable via a RepairsFlow or by linking to a website with information on how the user can solve it themselves.

Creating an issue

from homeassistant.helpers import issue_registry as ir

ir.async_create_issue(
hass,
DOMAIN,
"manual_migration",
breaks_in_ha_version="2022.9.0",
is_fixable=False,
severity=ir.IssueSeverity.ERROR,
translation_key="manual_migration",
)
AttributeTypeDefaultDescription
domainstringDomain raising the issue
issue_idstringAn identifier for the issue, must be unique within domain
breaks_in_ha_versionstringNoneThe version in which the issue is breaking
datadictNoneArbitrary data, not shown to the user
is_fixablebooleanTrue if the issue can be automatically fixed
is_persistentbooleanTrue if the issue should persists across restarts of Home Assistant
issue_domainstringNoneSet by integrations creating issues on behalf of other integrations
learn_more_urlstringNoneURL where the user can find more details about an issue
severityIssueSeveritySeverity of the issue
translation_keystrTranslation key with a brief explanation of the issue
translation_placeholdersdictNonePlaceholders which will be injected in the translation

Severity of an issue

To better understand which severity level to choose, see the list below.

IssueSeverityDescription
CRITICALConsidered reserved, only used for true panic
ERRORSomething is currently broken and needs immediate attention
WARNINGSomething breaks in the future (e.g., API shutdown) and needs attention

Offering a repair

Create a new platform file in your integration folder called repairs.py and add code according to the pattern below.

from __future__ import annotations

import voluptuous as vol

from homeassistant import data_entry_flow
from homeassistant.components.repairs import ConfirmRepairFlow, RepairsFlow
from homeassistant.core import HomeAssistant


class Issue1RepairFlow(RepairsFlow):
"""Handler for an issue fixing flow."""

async def async_step_init(
self, user_input: dict[str, str] | None = None
) -> data_entry_flow.FlowResult:
"""Handle the first step of a fix flow."""

return await (self.async_step_confirm())

async def async_step_confirm(
self, user_input: dict[str, str] | None = None
) -> data_entry_flow.FlowResult:
"""Handle the confirm step of a fix flow."""
if user_input is not None:
return self.async_create_entry(title="", data={})

return self.async_show_form(step_id="confirm", data_schema=vol.Schema({}))


async def async_create_fix_flow(
hass: HomeAssistant,
issue_id: str,
data: dict[str, str | int | float | None] | None,
) -> RepairsFlow:
"""Create flow."""
if issue_id == "issue_1":
return Issue1RepairFlow()

Issue life cycle

Issue persistence

An issue will be kept in the issue registry until it's removed by the integration that created it or by the user fixing it.

The is_persistent flag controls if an issue should be shown to the user after a restart of Home Assistant:

  • If the is_persistent flag is set on the issue, the issue will be shown again to the user after a restart. Use this for issues that can only be detected when they occur (update failed, unknown action in automation).
  • If the is_persistent flag is not set on the issue, the issue will not be shown again to the user after a restart until it's created again by its integration. Use this for issues that can be checked for, like low disk space.

Ignored issues

It's possible for the user to "ignore" issues. An ignored issue is ignored until it's explicitly deleted - either by the integration or by the user successfully walking through its repair flow - and then created again. Ignoring an issue takes effect across restarts of Home Assistant regardless of issue persistence.

Deleting an issue

Integrations typically don't need to delete issues, but it may be useful in some cases.

from homeassistant.helpers import issue_registry as ir

ir.async_delete_issue(hass, DOMAIN, "manual_migration")

Fixing an issue

If an issue has the is_fixable issue set to True, the user will be allowed to fix the issue. An issue which is succesfully fixed will be removed from the issue registry.