home-assistant/core · warning · BackupNotFound

Backup {backup_id} not found

Error message

Backup {backup_id} not found

What it means

BackupNotFound raised in _get_file_for_download when _find_file_and_metadata_version_by_id returns no file for the backup_id. The B2 backup agent cannot start a download because the corresponding file version no longer exists (or its metadata file no longer identifies it).

Source

Thrown at homeassistant/components/backblaze_b2/backup.py:209

        try:
            await self._hass.async_add_executor_job(_delete_uploaded_file)
        except B2Error:
            _LOGGER.warning(
                "Failed to clean up partially uploaded backup file %s;"
                " manual deletion from Backblaze B2 may be required",
                filename,
            )
        else:
            _LOGGER.debug(
                "Successfully deleted partially uploaded main backup file %s", filename
            )

    async def _get_file_for_download(self, backup_id: str) -> FileVersion:
        """Get backup file for download, raising if not found."""
        file, _ = await self._find_file_and_metadata_version_by_id(backup_id)
        if not file:
            raise BackupNotFound(f"Backup {backup_id} not found")
        return file

    @handle_b2_errors
    @override
    async def async_download_backup(
        self, backup_id: str, **kwargs: Any
    ) -> AsyncIterator[bytes]:
        """Download a backup from Backblaze B2."""
        file = await self._get_file_for_download(backup_id)
        _LOGGER.debug("Downloading %s", file.file_name)

        downloaded_file = await self._hass.async_add_executor_job(file.download)
        response = downloaded_file.response

        async def stream_response() -> AsyncIterator[bytes]:
            """Stream the response into an AsyncIterator."""
            try:
                iterator = response.iter_content(chunk_size=1024 * 1024)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Refresh the backup list and download using a current id
2. If the file exists in B2, verify its sidecar metadata file maps backup_id correctly
3. Manage retention inside HA rather than deleting files directly in B2

backups = await agent.async_list_backups()
if backup_id not in {b.backup_id for b in backups}:
    # don't attempt download; refresh UI

from homeassistant.components.backup.exceptions import BackupNotFound

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

try:
    file = await self._get_file_for_download(backup_id)
except BackupNotFound:
    # refresh list, pick a valid id
    ...

When it happens

Trigger: async_download_backup(backup_id) where the B2 bucket has no file whose companion metadata maps to that id — deleted externally, hidden by lifecycle rules, or recorded under an older metadata format.

Common situations: Backup deleted in the Backblaze console or by B2 lifecycle rules, stale backup list after restoring HA from a backup, metadata file out of sync with main file.

Related errors

• invalid_bucket_name
• Failed during {func.__name__}: {err}
• Upload timed out after {UPLOAD_TIMEOUT} seconds
• 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/022aeba0cb1933f8. Report an issue: GitHub.