home-assistant/core · error · HomeAssistantError

Failed to connect

Error message

Failed to connect

What it means

Raised by the airos reboot button entity when async_press fails with any AirOSException while logging in to or rebooting a Ubiquiti airOS device. It wraps the underlying library exception in a HomeAssistantError with the 'cannot_connect' translation key, so the user sees a localized 'Failed to connect' message in the UI. The original exception is chained via 'from err' so it appears in logs.

Source

Thrown at homeassistant/components/airos/button.py:63

        self,
        coordinator: AirOSDataUpdateCoordinator,
        description: ButtonEntityDescription,
    ) -> None:
        """Initialize the AirOS client button."""
        super().__init__(coordinator)

        self.entity_description = description
        self._attr_unique_id = f"{coordinator.data.derived.mac}_{description.key}"

    @override
    async def async_press(self) -> None:
        """Handle the button press to reboot the device."""
        try:
            await self.coordinator.airos_device.login()
            result = await self.coordinator.airos_device.reboot()

        except AirOSException as err:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="cannot_connect",
            ) from err

        if not result:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="reboot_failed",
            ) from None

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Verify the device is reachable: open its web interface at the configured host and confirm it responds.
2. Check the username/password stored in the airos config entry and re-configure if the device credentials changed.
3. Inspect the full traceback in Home Assistant logs (the chained AirOSException names the real cause, e.g. authentication vs connection setup).
4. If the device IP changed, set a DHCP reservation or update the config entry host.
5. Update the airos integration/library to the latest version in case the device firmware introduced API changes.

def is_airos_connect_error(err: Exception) -> bool:
    return isinstance(err, HomeAssistantError) and getattr(err, "translation_domain", None) == "airos" and getattr(err, "translation_key", None) == "cannot_connect"

try:
    await button.async_press()  # or call device.reboot() via airos library directly
except HomeAssistantError as err:
    if getattr(err, "translation_key", None) == "cannot_connect":
        # connectivity problem: check host reachability before retry
        ...
    raise

When it happens

Trigger: Calling async_press on the reboot button when airos_device.login() or airos_device.reboot() raises any subclass of AirOSException: wrong IP/hostname, device powered off or unreachable on the network, HTTP session setup failure, timeout, or invalid credentials (AirOSConnectionAuthenticationError is also caught here since it subclasses AirOSException).

Common situations: Device IP changed by DHCP, firmware update changed the login flow or cookie handling, wrong username/password in the config entry, device rebooting already, or TLS/certificate mismatch after a firmware upgrade.

Related errors

• The device did not accept the reboot request. Try again, or
• Failed to connect
• Connection failed during firmware update
• Credential is already linked to a user
• Unable find multi-factor auth module: {mfa_module_id}

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