home-assistant/core · error · BackupManagerError

At least one available backup agent must be selected, got {a

Error message

At least one available backup agent must be selected, got {agent_ids}

What it means

Raised by BackupManager.async_create_backup when none of the requested agent_ids is a registered, available backup agent. The manager splits the request into available_agents and unavailable_agents; if the available list is empty it refuses to start — a backup would have nowhere to be stored (including the local agent, which counts as an agent).

Source

Thrown at homeassistant/components/backup/manager.py:1176

        include_all_addons: bool,
        include_database: bool,
        include_folders: list[Folder] | None,
        include_homeassistant: bool,
        name: str | None,
        password: str | None,
        raise_task_error: bool,
        with_automatic_settings: bool,
    ) -> NewBackup:
        """Initiate generating a backup."""
        unavailable_agents = [
            agent_id for agent_id in agent_ids if agent_id not in self.backup_agents
        ]
        if not (
            available_agents := [
                agent_id for agent_id in agent_ids if agent_id in self.backup_agents
            ]
        ):
            raise BackupManagerError(
                f"At least one available backup agent must be selected, got {agent_ids}"
            )
        if unavailable_agents:
            LOGGER.warning(
                "Backup agents %s are not available, will backup to %s",
                unavailable_agents,
                available_agents,
            )
        if include_all_addons and include_addons:
            raise BackupManagerError(
                "Cannot include all addons and specify specific addons"
            )

        kind = "Automatic" if with_automatic_settings else "Custom"
        backup_name = (
            name if name is None else name.strip()
        ) or f"{kind} backup {HAVERSION}"
        extra_metadata = extra_metadata or {}

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Fetch valid IDs first: use the manager's backup_agents keys (or the UI's agent list) and pass those.
2. Include the local agent ('backup.local') if local storage is acceptable.
3. Re-enable/reload the integration providing the target agent, then retry.
4. Use exact agent IDs (integration domain + entry suffix), not bare integration domains.

Example fix

# before
await manager.async_create_backup(agent_ids=["backblaze"], ...)

# after
valid = list(manager.backup_agents)  # e.g. ['backup.local', 'backblaze_b2.abcdef']
await manager.async_create_backup(agent_ids=valid, ...)

valid_agents = [
    a for a in agent_ids if a in manager.backup_agents
]
if not valid_agents:
    raise ValueError(
        f"no valid agents in {agent_ids}; known: {list(manager.backup_agents)}"
    )

from homeassistant.components.backup.manager import BackupManagerError

try:
    await manager.async_create_backup(agent_ids=agent_ids, ...)
except BackupManagerError as err:
    if "must be selected" in str(err):
        agent_ids = list(manager.backup_agents)
        await manager.async_create_backup(agent_ids=agent_ids, ...)
    else:
        raise

When it happens

Trigger: Calling async_create_backup with agent_ids=[] (or only unknown/unloaded agents); passing a domain string like 'backblaze' instead of the full agent_id 'backblaze_b2.xxx'; the target agent's config entry being disabled/unloaded so it is not in manager.backup_agents.

Common situations: Scripts/websocket calls passing malformed agent IDs; the named network agent was removed or its integration entry disabled; passing empty list expecting a default (there is none — local agent must be requested explicitly as 'backup.local').

Related errors

• Cannot include all addons and specify specific addons
• Invalid agent selected: {agent_id}
• Refusing to write outside {self._backup_dir}: {candidate}
• Invalid filename: {suggested_filename}
• {err}

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