home-assistant/core · error · BackupNotFound

Backup {backup_id} not found

Error message

Backup {backup_id} not found

What it means

BackupNotFound raised in azure_storage async_download_backup when no blob's metadata matches the requested backup_id (checked via _find_blob_by_backup_id with metadata_version filtering). It tells the backup manager the requested backup no longer exists in the Azure container.

Source

Thrown at homeassistant/components/azure_storage/backup.py:126

    def __init__(self, hass: HomeAssistant, entry: AzureStorageConfigEntry) -> None:
        """Initialize the Azure storage backup agent."""
        super().__init__()
        self._client = entry.runtime_data
        self.name = entry.title
        self.unique_id = entry.entry_id

    @handle_backup_errors
    @override
    async def async_download_backup(
        self,
        backup_id: str,
        **kwargs: Any,
    ) -> AsyncIterator[bytes]:
        """Download a backup file."""
        blob = await self._find_blob_by_backup_id(backup_id)
        if blob is None:
            # pylint: disable-next=home-assistant-exception-not-translated
            raise BackupNotFound(f"Backup {backup_id} not found")
        download_stream = await self._client.download_blob(blob.name)
        return download_stream.chunks()

    @handle_backup_errors
    @override
    async def async_upload_backup(
        self,
        *,
        open_stream: Callable[[], Coroutine[Any, Any, AsyncIterator[bytes]]],
        backup: AgentBackup,
        on_progress: OnProgressCallback,
        **kwargs: Any,
    ) -> None:
        """Upload a backup."""

        metadata = {
            "metadata_version": METADATA_VERSION,
            "backup_id": backup.backup_id,

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Refresh the backup list (async_list_backups) and use an id that is currently present
2. If blobs exist but are not found, check their blob metadata has metadata_version matching METADATA_VERSION and a backup_id key
3. Remove stale entries by letting the manager reconcile, or delete and recreate the backup
4. Avoid external deletion; manage lifecycle through supported retention settings

backups = await agent.async_list_backups()
ids = {b.backup_id for b in backups}
if backup_id not in ids:
    # skip download, refresh UI list

from homeassistant.components.backup.exceptions import BackupNotFound

def is_backup_not_found(err: BaseException) -> bool:
    return isinstance(err, BackupNotFound)

try:
    stream = await agent.async_download_backup(backup_id)
except BackupNotFound:
    # stale id: refresh list and inform user
    ...

When it happens

Trigger: Calling async_download_backup with a backup_id that has no matching blob metadata: blob deleted externally, uploaded with an older METADATA_VERSION, or metadata stripped by a lifecycle/copy process.

Common situations: Backup deleted from the Azure portal or by a lifecycle management policy, HA restored from a backup where the agent's backup list is stale, metadata_version bump between HA versions.

Related errors

• account_not_found
• Error during backup operation in {func.__name__}: Status {er
• Timeout during backup operation in {func.__name__}
• Error during backup operation in {func.__name__}: {err}
• Backup {backup_id} not found

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