Skip to main content

Check during integration initialization if we are able to set it up correctly

Reasoning​

When we initialize an integration, we should check if we are able to set it up correctly. This way we can immediately let the user know that it doesn't work.

Implementing these checks increases the confidence that the integration will work correctly and provides a user-friendly way to show errors. This will improve the user experience.

Example implementation​

When the reason for the failure is temporary (like a temporary offline device), we should raise ConfigEntryNotReady and Home Assistant will retry the setup later. If the reason for the failure is that the password is incorrect or the api key is invalid, we should raise ConfigEntryAuthFailed and Home Assistant will ask the user to reauthenticate (if the reauthentication flow is implemented). If we don't expect the integration to work in the foreseeable future, we should raise ConfigEntryError.

__init__.py:

async def async_setup_entry(hass: HomeAssistant, entry: MyIntegrationConfigEntry) -> bool:
    """Set up my integration from a config entry."""

    client = MyClient(entry.data[CONF_HOST])
    
    try:
        await client.async_setup()
    except OfflineException:
        raise ConfigEntryNotReady("Device is offline")
    except InvalidAuthException:
        raise ConfigEntryAuthFailed("Invalid authentication")
    except AccountClosedException:
        raise ConfigEntryError("Account closed")

    entry.runtime_data = client

    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)

    return True
info

Please note that this may also be implemented implicitly when using a data update coordinator via await coordinator.async_config_entry_first_refresh().

Additional resources​

More information about config entries and their lifecycle can be found in the config entry documentation.

Exceptions​

There are no exceptions to this rule.

  • runtime-data: Use ConfigEntry.runtime_data to store runtime data