home-assistant/core · error · HomeAssistantError

Backup integration is not available

Error message

Backup integration is not available

What it means

Raised by homeassistant.components.backup.async_get_manager when the backup integration's manager is not yet (or no longer) in hass.data. Every consumer of backup functionality goes through this helper, so the error means the 'backup' integration is not set up in this Home Assistant instance at the moment of the call.

Source

Thrown at homeassistant/components/backup/__init__.py:152

    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)

    return True


async def async_unload_entry(hass: HomeAssistant, entry: BackupConfigEntry) -> bool:
    """Unload a config entry."""
    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)


@callback
def async_get_manager(hass: HomeAssistant) -> BackupManager:
    """Get the backup manager instance.

    Raises HomeAssistantError if the backup integration is not available.
    """
    if DATA_MANAGER not in hass.data:
        raise HomeAssistantError("Backup integration is not available")

    return hass.data[DATA_MANAGER]

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Make sure the 'backup' integration is installed and enabled (it is loaded via a config entry in the default setup).
2. Defer the call until after HOMEASSISTANT_STARTED (or await async_setup of the backup component) instead of calling during setup of another integration.
3. In tests, set up the backup integration with the standard mock/setup helpers so DATA_MANAGER is populated.
4. Handle HomeAssistantError from async_get_manager and surface a clear 'backup integration not available' state instead of crashing.

Example fix

// before
from homeassistant.components.backup import async_get_manager
manager = async_get_manager(hass)  # may raise during startup

// after
from homeassistant.components.backup import async_get_manager
from homeassistant.exceptions import HomeAssistantError

async def async_setup(hass, config):
    async def _start(_):
        try:
            manager = async_get_manager(hass)
        except HomeAssistantError:
            _LOGGER.error("Backup integration is not available")
            return
        ...
    hass.bus.async_listen_once(EVENT_HOMEASSISTANT_STARTED, _start)

from homeassistant.core import HomeAssistant
from homeassistant.components.backup import DATA_MANAGER

def backup_available(hass: HomeAssistant) -> bool:
    return DATA_MANAGER in hass.data

def backup_available(hass: HomeAssistant) -> TypeGuard[HomeAssistant]:
    return DATA_MANAGER in hass.data

from homeassistant.exceptions import HomeAssistantError
from homeassistant.components.backup import async_get_manager

try:
    manager = async_get_manager(hass)
except HomeAssistantError:
    LOGGER.error("Backup integration not available; skipping")
    return

When it happens

Trigger: Calling async_get_manager(hass) before the backup integration has finished setup (e.g., during startup, from another integration's async_setup that runs before 'backup' loads), after the backup config entry was unloaded/removed, or in a context (custom component, script at import time) where the integration was never loaded.

Common situations: Custom integrations or automations that call backup manager APIs at startup; the backup integration entry was disabled or deleted by the user; test harnesses that create hass without setting up the backup integration.

Related errors

• You need at least Home Assistant version {backup_meta_versio
• Failed during {func.__name__}
• Failed to upload backup
• Backup {backup_id} not found
• Backup {backup_id} not found

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/6566a399c9b44a32. Report an issue: GitHub.