What causes "Failed during {func.__name__}" in home-assistant/core?

Check the chained exception in logs (BackupAgentError.__cause__) to see the real botocore error code.

home-assistant/core · error · BackupAgentError

Failed during {func.name}

Error message

Failed during {func.__name__}

What it means

A decorator (handle_boto_errors) applied to S3 backup-agent methods that converts any BotoCoreError (superclass of ClientError, ConnectionError from botocore, EndpointConnectionError, etc.) into BackupAgentError with the message 'Failed during {func.__name__}'. The backup manager uses this to show a generic per-operation failure in the backup UI while the original cause stays chained in __cause__.

Source

Thrown at homeassistant/components/aws_s3/backup.py:49

# https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html
# We set the threshold to 20 MiB to avoid too many parts.
# Note that each part is allocated in the memory.
MULTIPART_MIN_PART_SIZE_BYTES = 20 * 2**20


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

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

    return wrapper


async def async_get_backup_agents(
    hass: HomeAssistant,
) -> list[BackupAgent]:
    """Return a list of backup agents."""
    entries: list[S3ConfigEntry] = hass.config_entries.async_loaded_entries(DOMAIN)
    return [S3BackupAgent(hass, entry) for entry in entries]


@callback
def async_register_backup_agents_listener(
    hass: HomeAssistant,
    *,
    listener: Callable[[], None],
    **kwargs: Any,

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Check the chained exception in logs (BackupAgentError.__cause__) to see the real botocore error code.
Fix the underlying cause: IAM permissions (s3:GetObject/s3:DeleteObject), network reachability, or credentials.
Retry the backup operation once transient issues (throttling, brief outage) clear.

Defensive patterns

Strategy: try-catch

Try / catch

from homeassistant.components.backup import BackupAgentError

try:
    await agent.async_download_backup(backup, path)
except BackupAgentError as err:
    root = err.__cause__  # original BotoCoreError carries the actionable code
    handle_botocore(root)

Prevention

Always inspect __cause__ — the wrapper message intentionally hides the detail.
Keep IAM permissions for download/delete aligned with upload permissions.
Retry once for transient botocore errors (throttle, connection) before alerting.

When it happens

Trigger: Any decorated backup operation (e.g. downloading, deleting, listing metadata) performs a boto3 call that raises BotoCoreError: network failure to S3, credential/permission error, throttling, or param validation.

Common situations: Backup download or delete fails because the IAM key lost permissions after initial setup worked; endpoint unreachable during a long backup restore; S3 throttled the request.

Related errors

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