home-assistant/core · error · BackupAgentError

Timeout downloading metadata for backup {backup_id}

Error message

Timeout downloading metadata for backup {backup_id}

What it means

Raised by the Backblaze B2 backup agent when downloading and parsing a backup's metadata file exceeds METADATA_DOWNLOAD_TIMEOUT. The metadata download runs in an executor job wrapped in asyncio.wait_for; on TimeoutError it is converted to a BackupAgentError with 'from None' so the original timeout is not chained. It indicates the B2 API/storage network was too slow, not that the backup is missing.

Source

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

                _LOGGER.debug("Returning backup %s from cache", backup_id)
                return backup

        file, metadata_file_version = await self._find_file_and_metadata_version_by_id(
            backup_id
        )
        if not file or not metadata_file_version:
            raise BackupNotFound(f"Backup {backup_id} not found")

        try:
            metadata_content = await asyncio.wait_for(
                self._hass.async_add_executor_job(
                    self._download_and_parse_metadata_sync,
                    metadata_file_version,
                ),
                timeout=METADATA_DOWNLOAD_TIMEOUT,
            )
        except TimeoutError:
            raise BackupAgentError(
                f"Timeout downloading metadata for backup {backup_id}"
            ) from None

        _LOGGER.debug(
            "Successfully retrieved metadata for backup ID %s from file %s",
            backup_id,
            metadata_file_version.file_name,
        )
        backup = _create_backup_from_metadata(metadata_content, file)

        if self._is_cache_valid(self._backup_list_cache_expiration):
            self._backup_list_cache[backup.backup_id] = backup

        return backup

    async def _find_file_and_metadata_version_by_id(
        self, backup_id: str
    ) -> tuple[FileVersion | None, FileVersion | None]:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Retry the operation after a short wait — B2 timeouts are usually transient.
2. Check network throughput and latency to Backblaze (e.g., b2 authorize-account / b2 download_file_by_name in a shell, or a speed test) and free upstream bandwidth.
3. Verify the B2 service status and that the application key/bucket are not being rate-limited.
4. If it persists, raise METADATA_DOWNLOAD_TIMEOUT in a local patch or file an issue with the integration.

from homeassistant.components.backup.agent import BackupAgentError

for attempt in range(3):
    try:
        return await agent.async_get_backup(backup_id)
    except BackupAgentError as err:
        if "Timeout downloading metadata" not in str(err) or attempt == 2:
            raise
        await asyncio.sleep(2 ** attempt)

When it happens

Trigger: Calling async_get_backup on the B2 agent when the executor job _download_and_parse_metadata_sync does not finish within METADATA_DOWNLOAD_TIMEOUT seconds: slow or rate-limited B2 endpoint, saturated upstream bandwidth, transient network stall, or DNS/proxy delays on the way to api.backblazeb2.com.

Common situations: Home Assistant on a slow or congested network (backup traffic, large downloads in parallel); B2 transient outage or throttling; running on Raspberry Pi-class hardware with constrained I/O; restrictive firewall/proxy adding latency.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Timeout during backup operation in {func.__name__}
• Failed to connect
• {error}
• {address}: {ex}
• api_timeout

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