home-assistant/core · error · BackupManagerError

Backup {backup_id} not found in agent {agent_id}

Error message

Backup {backup_id} not found in agent {agent_id}

What it means

Raised by BackupManager._async_restore_backup when the selected agent's async_get_backup(backup_id) raises BackupNotFound. The manager resolves the backup through the specific agent chosen for the restore (agent_id), so this means that particular agent does not hold a backup with that ID — even if other agents do.

Source

Thrown at homeassistant/components/backup/manager.py:1408

            self.async_on_backup_event(IdleEvent())

    async def _async_restore_backup(
        self,
        backup_id: str,
        *,
        agent_id: str,
        password: str | None,
        restore_addons: list[str] | None,
        restore_database: bool,
        restore_folders: list[Folder] | None,
        restore_homeassistant: bool,
    ) -> None:
        """Initiate restoring a backup."""
        agent = self.backup_agents[agent_id]
        try:
            backup = await agent.async_get_backup(backup_id)
        except BackupNotFound as err:
            raise BackupManagerError(
                f"Backup {backup_id} not found in agent {agent_id}"
            ) from err
        # Check for None to be backwards compatible with the old BackupAgent API,
        # this can be removed in HA Core 2025.10
        if not backup:
            frame.report_usage(
                "returns None from BackupAgent.async_get_backup",
                breaks_in_ha_version="2025.10",
                integration_domain=agent_id.partition(".")[0],
            )
            raise BackupManagerError(
                f"Backup {backup_id} not found in agent {agent_id}"
            )

        async def open_backup() -> AsyncIterator[bytes]:
            return await agent.async_download_backup(backup_id)

        await self._reader_writer.async_restore_backup(

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Refresh the backup list for that agent and restore using the refreshed backup_id, with the agent that actually reports it.
  2. If the backup exists locally only, select the local agent ('backup.local') for the restore.
  3. Verify the agent integration is loaded and can list its backups (its async_list_backups) before restoring.
Defensive patterns

Strategy: validation

Validate before calling

agent = manager.backup_agents[agent_id]
found = await agent.async_get_backup(backup_id)  # may raise BackupNotFound
# safer: confirm membership via list
ids = {b.backup_id for b in await agent.async_list_backups()}
if backup_id not in ids:
    raise ValueError(f"{backup_id} not held by {agent_id}")

Try / catch

from homeassistant.components.backup.manager import BackupManagerError

try:
    await manager.async_restore_backup(backup_id, agent_id=agent_id, ...)
except BackupManagerError as err:
    if "not found in agent" in str(err):
        holding = [a for a, ag in manager.backup_agents.items()
                   if backup_id in {b.backup_id for b in await ag.async_list_backups()}]
        if holding:
            await manager.async_restore_backup(backup_id, agent_id=holding[0], ...)
        else:
            raise
    raise

Prevention

When it happens

Trigger: Calling restore with a backup_id/agent_id pair that does not match: the backup exists on the local agent but the request targets a network agent (or vice versa); the backup was deleted from that agent; a stale UI entry referencing a removed remote backup.

Common situations: Backup deleted from the network agent (B2, Google Drive, etc.) while still shown in the UI; agent integrations reloaded/changed so IDs shifted; mixed local/remote backup lists with the wrong agent selected.

Related errors

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