{"record":{"id":"e1e001af6fcb7f1e","repo":"home-assistant/core","slug":"timeout-downloading-metadata-for-backup-backup-id","errorCode":null,"errorMessage":"Timeout downloading metadata for backup {backup_id}","messagePattern":"Timeout downloading metadata for backup (.+?)","errorType":"exception","errorClass":"BackupAgentError","httpStatus":null,"severity":"error","filePath":"homeassistant/components/backblaze_b2/backup.py","lineNumber":491,"sourceCode":"                _LOGGER.debug(\"Returning backup %s from cache\", backup_id)\n                return backup\n\n        file, metadata_file_version = await self._find_file_and_metadata_version_by_id(\n            backup_id\n        )\n        if not file or not metadata_file_version:\n            raise BackupNotFound(f\"Backup {backup_id} not found\")\n\n        try:\n            metadata_content = await asyncio.wait_for(\n                self._hass.async_add_executor_job(\n                    self._download_and_parse_metadata_sync,\n                    metadata_file_version,\n                ),\n                timeout=METADATA_DOWNLOAD_TIMEOUT,\n            )\n        except TimeoutError:\n            raise BackupAgentError(\n                f\"Timeout downloading metadata for backup {backup_id}\"\n            ) from None\n\n        _LOGGER.debug(\n            \"Successfully retrieved metadata for backup ID %s from file %s\",\n            backup_id,\n            metadata_file_version.file_name,\n        )\n        backup = _create_backup_from_metadata(metadata_content, file)\n\n        if self._is_cache_valid(self._backup_list_cache_expiration):\n            self._backup_list_cache[backup.backup_id] = backup\n\n        return backup\n\n    async def _find_file_and_metadata_version_by_id(\n        self, backup_id: str\n    ) -> tuple[FileVersion | None, FileVersion | None]:","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/backblaze_b2/backup.py#L473-L509","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Retry the operation after a short wait — B2 timeouts are usually transient.","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.","Verify the B2 service status and that the application key/bucket are not being rate-limited.","If it persists, raise METADATA_DOWNLOAD_TIMEOUT in a local patch or file an issue with the integration."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"from homeassistant.components.backup.agent import BackupAgentError\n\nfor attempt in range(3):\n    try:\n        return await agent.async_get_backup(backup_id)\n    except BackupAgentError as err:\n        if \"Timeout downloading metadata\" not in str(err) or attempt == 2:\n            raise\n        await asyncio.sleep(2 ** attempt)","preventionTips":["Keep upstream bandwidth free during backup metadata/download operations.","Monitor B2 status pages during incidents instead of hammering retries.","Cache/refresh the backup list (it also warms the agent's cache) before detailed lookups."],"tags":["backup","backblaze-b2","timeout","network"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}