home-assistant/core · error · BackupAgentError

Error during backup operation in {func.name}: Status {er

Error message

Error during backup operation in {func.__name__}: Status {err.status_code}, message: {err.message}

What it means

BackupAgentError raised by the handle_backup_errors decorator in azure_storage/backup.py when a backup operation (upload/download/delete/list) fails with azure.core.exceptions.HttpResponseError. It wraps HTTP-level failures from the Blob service (4xx/5xx with status_code and message) and is logged at debug with the full traceback before re-raising.

Source

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

) -> Callable[Concatenate[AzureStorageBackupAgent, P], Coroutine[Any, Any, _R]]:
    """Handle backup errors."""

    @wraps(func)
    async def wrapper(
        self: AzureStorageBackupAgent, *args: P.args, **kwargs: P.kwargs
    ) -> _R:
        try:
            return await func(self, *args, **kwargs)
        except HttpResponseError as err:
            _LOGGER.debug(
                "Error during backup in %s: Status %s, message %s",
                func.__name__,
                err.status_code,
                err.message,
                exc_info=True,
            )
            # pylint: disable-next=home-assistant-exception-not-translated
            raise BackupAgentError(
                f"Error during backup operation in {func.__name__}:"
                f" Status {err.status_code}, message: {err.message}"
            ) from err
        except ServiceRequestError as err:
            # pylint: disable-next=home-assistant-exception-not-translated
            raise BackupAgentError(
                f"Timeout during backup operation in {func.__name__}"
            ) from err
        except AzureError as err:
            _LOGGER.debug(
                "Error during backup in %s: %s",
                func.__name__,
                err,
                exc_info=True,
            )
            # pylint: disable-next=home-assistant-exception-not-translated
            raise BackupAgentError(
                f"Error during backup operation in {func.__name__}: {err}"

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Read the Status and message in the exception (also in debug logs) to identify the HTTP failure mode
404: the blob vanished (e.g. deleted outside HA); refresh the backup list and retry with an existing backup id
429/503: retry after a delay; Azure SDK retries are exhausted — reduce backup size or schedule
403: re-authenticate the integration (SAS/key rotation invalidates the stored client)

Defensive patterns

Strategy: try-catch

Type guard

def is_http_response_error(err: BaseException) -> bool:
    from azure.core.exceptions import HttpResponseError
    return isinstance(err, HttpResponseError)

Try / catch

from homeassistant.components.backup.exceptions import BackupAgentError
try:
    async for chunk in await agent.async_download_backup(backup_id):
        ...
except BackupAgentError as err:
    # inspect err.__cause__ for status_code / message
    ...

Prevention

Always check backup existence via async_get_backup/list before acting on an id
Enable debug logging for the azure_storage integration to capture status codes
Handle BackupAgentError at the caller and branch on __cause__ type

When it happens

Trigger: Any decorated method (async_download_backup, async_upload_backup, async_delete_backup, async_get_backup) triggers an HttpResponseError, e.g. 404 on download_blob of a deleted blob, 412 precondition failure, or 503 server busy.

Common situations: Blob deleted between list and download (race), container permissions changed mid-operation, Azure throttling during large backup uploads, partial metadata causing wrong blob names.

Related errors

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