home-assistant/core · error · BackupAgentError

Timeout during backup operation in {func.__name__}

Error message

Timeout during backup operation in {func.__name__}

What it means

BackupAgentError raised by handle_backup_errors when an azure.core.exceptions.ServiceRequestError occurs during an Azure Storage backup operation. ServiceRequestError indicates the request was never successfully delivered (connection error, DNS failure, client-side timeout), so it is reported distinctly as a 'Timeout during backup operation'.

Source

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

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

    return wrapper


class AzureStorageBackupAgent(BackupAgent):

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Verify network/DNS from the HA host to the storage endpoint
2. For recurring upload timeouts, schedule backups when the uplink is idle or split large backups
3. Retry the backup operation once connectivity is restored; HA's backup manager can retrigger
4. If behind a proxy, ensure it permits long-lived streaming connections

import socket
socket.gethostbyname(f"{account_name}.blob.core.windows.net")  # DNS pre-check before long backup

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

except ServiceRequestError as err:
    raise BackupAgentError(f"Timeout during backup operation in {func.__name__}") from err

When it happens

Trigger: Network-level failure while calling blob APIs: connection reset, DNS resolution failure for <account>.blob.core.windows.net, or the request timing out client-side during upload/download of a large backup.

Common situations: HA host loses internet mid-backup, slow uplink causing large backup uploads to time out, restrictive firewall or DNS failure, container running with a small keepalive window.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• cannot_connect
• Error during backup operation in {func.__name__}: Status {er
• Error during backup operation in {func.__name__}: {err}
• Backup {backup_id} not found
• Timeout downloading metadata for backup {backup_id}

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