home-assistant/core · error · BackupAgentError

Failed during {func.__name__}: {err}

Error message

Failed during {func.__name__}: {err}

What it means

BackupAgentError raised by the handle_b2_errors decorator when any b2sdk B2Error escapes a decorated backup method. The message embeds the failing method name and the B2 error text, and the original B2Error is chained as __cause__ for diagnosis.

Source

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

    Uses the associated backup file to set the size.
    """
    metadata = metadata_content["backup_metadata"]
    metadata["size"] = backup_file.size
    return AgentBackup.from_dict(metadata)


def handle_b2_errors[T](
    func: Callable[..., Coroutine[Any, Any, T]],
) -> Callable[..., Coroutine[Any, Any, T]]:
    """Handle B2Errors by converting them to BackupAgentError."""

    @functools.wraps(func)
    async def wrapper(*args: Any, **kwargs: Any) -> T:
        """Catch B2Error and raise BackupAgentError."""
        try:
            return await func(*args, **kwargs)
        except B2Error as err:
            raise BackupAgentError(f"Failed during {func.__name__}: {err}") from err

    return wrapper


async def async_get_backup_agents(
    hass: HomeAssistant,
) -> list[BackupAgent]:
    """Return a list of backup agents for all configured Backblaze B2 entries."""
    entries: list[BackblazeConfigEntry] = hass.config_entries.async_loaded_entries(
        DOMAIN
    )
    return [BackblazeBackupAgent(hass, entry) for entry in entries]


@callback
def async_register_backup_agents_listener(
    hass: HomeAssistant,
    *,

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Read the embedded B2 error text (and __cause__) to identify the operation and failure reason
2. Cap exceeded: free space or raise the B2 storage cap, then retry the backup
3. Auth errors: reauth the integration and retry
4. Transient errors: rerun the backup; the manager reports failure and can be retriggered

import b2sdk.v2.exception as b2exc

def is_b2_error(err: BaseException) -> bool:
    return isinstance(err, b2exc.B2Error)

from homeassistant.components.backup.exceptions import BackupAgentError
try:
    await agent.async_upload_backup(open_stream=open_stream, backup=backup, on_progress=cb)
except BackupAgentError as err:
    cause = err.__cause__  # original B2Error — branch on its type

When it happens

Trigger: Any B2Error during download/upload/delete/list: BadRequest, FileNotPresent, Unauthorized (SAS-like auth failures with B2), B2ConnectionError, ServiceUnavailable, CapExceededExceededB2Account (storage cap) during upload.

Common situations: Storage cap exceeded mid-backup, file already deleted (FileNotPresent) on delete/download, key capabilities insufficient for writeFiles, network errors during large uploads.

Related errors

• Backup {backup_id} not found
• Upload timed out after {UPLOAD_TIMEOUT} seconds
• invalid_credentials
• restricted_bucket
• invalid_bucket_name

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