ha-repairs

Home Assistant Repair Issues

Repair issues provide actionable notifications to users about problems that require attention. Gold tier IQS requirement.

When to Use Repairs

Use repair issues for:

• Configuration problems the user can fix
• Firmware updates available
• Deprecated features being used
• Missing optional dependencies
• Service disruptions with user action needed

Do NOT use for:

• Transient errors (use logging)
• Entity unavailability (use available property)
• Internal errors (use exceptions)

Basic Implementation

from homeassistant.helpers import issue_registry as ir

# Create an issue
ir.async_create_issue(
    hass,
    DOMAIN,
    "firmware_update_available",
    is_fixable=False,
    severity=ir.IssueSeverity.WARNING,
    translation_key="firmware_update_available",
    translation_placeholders={
        "current_version": "1.0.0",
        "new_version": "2.0.0",
    },
)

Severity Levels

from homeassistant.helpers.issue_registry import IssueSeverity

IssueSeverity.CRITICAL  # Reserved for HA-internal use — do NOT use in custom integrations
IssueSeverity.ERROR     # Something is broken
IssueSeverity.WARNING   # Should be addressed soon

Custom integrations should use ERROR or WARNING; CRITICAL is reserved for Home Assistant core.

Issue Types

Non-Fixable Issue

User must take action outside Home Assistant:

ir.async_create_issue(
    hass,
    DOMAIN,
    "device_firmware_outdated",
    is_fixable=False,
    severity=ir.IssueSeverity.WARNING,
    translation_key="device_firmware_outdated",
    translation_placeholders={
        "device": device_name,
        "version": current_version,
    },
    learn_more_url="https://example.com/firmware-update",
)

Fixable Issue (with Repair Flow)

User can fix directly in Home Assistant:

# In __init__.py or where issue is detected
ir.async_create_issue(
    hass,
    DOMAIN,
    f"reauth_required_{entry.entry_id}",
    is_fixable=True,
    severity=ir.IssueSeverity.ERROR,
    translation_key="reauth_required",
    data={"entry_id": entry.entry_id},
)