home-assistant/core · error · BackupAgentError

Error during backup operation in {func.__name__}: {err}

Error message

Error during backup operation in {func.__name__}: {err}

What it means

BackupAgentError raised by handle_backup_errors as the catch-all for any azure.core.exceptions.AzureError that is not HttpResponseError or ServiceRequestError, during Azure Storage backup operations. The original error text is embedded via str(err). This covers SDK/client-level failures outside plain HTTP responses.

Source

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

            # 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}"
            ) from err

    return wrapper


class AzureStorageBackupAgent(BackupAgent):
    """Azure storage backup agent."""

    domain = DOMAIN

    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

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Inspect the embedded error text and the debug log (exc_info=True) to identify the underlying AzureError
2. ClientAuthenticationError mid-operation: reissue credentials in the integration and retry the backup
3. For long uploads, prefer account-key or non-expiring auth over short-lived SAS tokens
4. Retry the backup after fixing the underlying cause; the backup agent reports failure to the backup manager

def is_azure_error(err: BaseException) -> bool:
    from azure.core.exceptions import AzureError, HttpResponseError, ServiceRequestError
    return isinstance(err, AzureError) and not isinstance(err, (HttpResponseError, ServiceRequestError))

except AzureError as err:
    _LOGGER.debug("Error during backup in %s: %s", func.__name__, err, exc_info=True)
    raise BackupAgentError(f"Error during backup operation in {func.__name__}: {err}") from err

When it happens

Trigger: Decorated backup methods raise an AzureError subclass such as ClientAuthenticationError mid-operation (SAS expiring during a long upload) or HttpResponseError edge subclasses not matched earlier.

Common situations: SAS token expiring during a multi-hour backup upload, credential/permission revocation mid-session, SDK internal errors after connection pool exhaustion.

Related errors

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

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