home-assistant/core · error · BackupManagerError

Invalid agent selected: {agent_id}

Error message

Invalid agent selected: {agent_id}

What it means

Raised by BackupManager.async_can_decrypt_on_download when the given agent_id is not a key in manager.backup_agents (KeyError on dict access, re-raised as BackupManagerError). It is a pure input-validation failure: the decrypt-check is asked about an agent that is not registered/loaded.

Source

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

                        )
                        or "-"
                    ),
                    "failed_folders": ", ".join(f for f in folder_errors) or "-",
                },
            )

    async def async_can_decrypt_on_download(
        self,
        backup_id: str,
        *,
        agent_id: str,
        password: str | None,
    ) -> None:
        """Check if we are able to decrypt the backup on download."""
        try:
            agent = self.backup_agents[agent_id]
        except KeyError as err:
            raise BackupManagerError(f"Invalid agent selected: {agent_id}") from err
        try:
            backup = await agent.async_get_backup(backup_id)
        except BackupNotFound as err:
            raise BackupManagerError(
                f"Backup {backup_id} not found in agent {agent_id}"
            ) from err
        # Check for None to be backwards compatible with the old BackupAgent API,
        # this can be removed in HA Core 2025.10
        if not backup:
            frame.report_usage(
                "returns None from BackupAgent.async_get_backup",
                breaks_in_ha_version="2025.10",
                integration_domain=agent_id.partition(".")[0],
            )
            raise BackupManagerError(
                f"Backup {backup_id} not found in agent {agent_id}"
            )
        reader: IO[bytes]

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Validate the agent_id against list(manager.backup_agents) (or the UI agent list) before calling.
2. Reload or re-enable the integration that provides the agent so it registers again, then retry.
3. Use full agent IDs including the config-entry suffix (e.g., 'backblaze_b2.abcdef123'), not the integration domain.

Example fix

# before
await manager.async_can_decrypt_on_download(
    backup_id, agent_id="backblaze", password=pw
)

# after
agent_id = next(a for a in manager.backup_agents if a.startswith("backblaze"))
await manager.async_can_decrypt_on_download(
    backup_id, agent_id=agent_id, password=pw
)

if agent_id not in manager.backup_agents:
    raise ValueError(
        f"unknown agent {agent_id}; known: {list(manager.backup_agents)}"
    )

def is_registered_agent(manager, agent_id: str) -> bool:
    return agent_id in manager.backup_agents

from homeassistant.components.backup.manager import BackupManagerError

try:
    await manager.async_can_decrypt_on_download(
        backup_id, agent_id=agent_id, password=password
    )
except BackupManagerError as err:
    if "Invalid agent selected" in str(err):
        agent_id = next(iter(manager.backup_agents), None)
        if agent_id is None:
            raise
        await manager.async_can_decrypt_on_download(
            backup_id, agent_id=agent_id, password=password
        )
    else:
        raise

When it happens

Trigger: Calling async_can_decrypt_on_download with a malformed or stale agent_id — bare domain instead of full agent_id, an agent whose config entry was removed/disabled, or an ID from a different HA instance; also races where the agent unloads between UI listing and the check.

Common situations: Scripts/websocket clients passing the wrong identifier; network agent integration uninstalled or entry disabled after the UI captured the ID; typos in automation payloads.

Related errors

• At least one available backup agent must be selected, got {a
• Backup {backup_id} does not exist
• Refusing to write outside {self._backup_dir}: {candidate}
• Invalid filename: {suggested_filename}
• Cannot include all addons and specify specific addons

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