home-assistant/core · error · BackupNotFound

Backup {backup_id} not found

Error message

Backup {backup_id} not found

What it means

Raised by the local backup agent (LocalBackupAgent, the 'backup.local' agent) when async_get_backup is asked for a backup_id that is not in the in-memory _backups map after the backup directory has been (re)loaded. The agent lazily loads the backup directory on first call, so the error means no backup with that ID is tracked locally.

Source

Thrown at homeassistant/components/backup/backup.py:106

    @override
    async def async_list_backups(self, **kwargs: Any) -> list[AgentBackup]:
        """List backups."""
        if not self._loaded_backups:
            await self._load_backups()
        return [backup for backup, _ in self._backups.values()]

    @override
    async def async_get_backup(
        self,
        backup_id: str,
        **kwargs: Any,
    ) -> AgentBackup:
        """Return a backup."""
        if not self._loaded_backups:
            await self._load_backups()

        if backup_id not in self._backups:
            raise BackupNotFound(f"Backup {backup_id} not found")

        backup, backup_path = self._backups[backup_id]
        if not await self._hass.async_add_executor_job(backup_path.exists):
            LOGGER.debug(
                (
                    "Removing tracked backup (%s) that does not exists on the expected"
                    " path %s"
                ),
                backup.backup_id,
                backup_path,
            )
            self._backups.pop(backup_id)
            raise BackupNotFound(f"Backup {backup_id} not found")

        return backup

    @override
    def get_backup_path(self, backup_id: str) -> Path:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Confirm the backup file still exists in the backup directory (default /backups on HAOS) and the mount is healthy.
2. Reload the backup integration or restart Home Assistant so the local agent rescans the directory.
3. Use the correct agent_id: check the backup's agents via the manager so the ID is looked up against the agent that actually holds it.

backups = await local_agent.async_list_backups()
if backup_id not in {b.backup_id for b in backups}:
    raise ValueError(f"unknown backup {backup_id}")

from homeassistant.components.backup.agent import BackupNotFound

try:
    backup = await local_agent.async_get_backup(backup_id)
except BackupNotFound:
    LOGGER.warning("Local backup %s missing", backup_id)
    await trigger_list_refresh()

When it happens

Trigger: Calling async_get_backup(backup_id) with an ID that does not correspond to any tar file previously seen in the local backup directory; the backup directory was moved or wiped (fresh install, /backups volume not mounted on HAOS); the ID belongs to a remote-agent-only backup.

Common situations: Restoring or inspecting a backup after the storage mount holding /backups was lost; a fresh Home Assistant OS install with old backup records in the UI; passing an agent-reported ID from a different agent (e.g., a cloud agent's ID) to the local agent.

Related errors

• Backup {backup_id} not found
• Backup {backup_id} does not exist
• You need at least Home Assistant version {backup_meta_versio
• pipeline_not_found
• Failed during {func.__name__}

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