home-assistant/core · error · UpdateFailed

Failed to connect

Error message

Failed to connect

What it means

UpdateFailed raised by the airos data fetch helper when connecting to the airOS device fails at setup, during the device connection, or times out. It signals a transient or persistent connectivity problem; Home Assistant will retry the coordinator update according to its backoff schedule and mark entities unavailable in the meantime.

Source

Thrown at homeassistant/components/airos/coordinator.py:66

    airos_device: AirOSDeviceDetect,
    update_method: Callable[[], Awaitable[T]],
) -> T:
    """Fetch data from AirOS device."""
    try:
        await airos_device.login()
        return await update_method()
    except AirOSConnectionAuthenticationError as err:
        _LOGGER.exception("Error authenticating with airOS device")
        raise ConfigEntryAuthFailed(
            translation_domain=DOMAIN, translation_key="invalid_auth"
        ) from err
    except (
        AirOSConnectionSetupError,
        AirOSDeviceConnectionError,
        TimeoutError,
    ) as err:
        _LOGGER.error("Error connecting to airOS device: %s", err)
        raise UpdateFailed(
            translation_domain=DOMAIN,
            translation_key="cannot_connect",
        ) from err
    except AirOSDataMissingError as err:
        _LOGGER.error("Expected data not returned by airOS device: %s", err)
        raise UpdateFailed(
            translation_domain=DOMAIN,
            translation_key="error_data_missing",
        ) from err


class AirOSDataUpdateCoordinator(DataUpdateCoordinator[AirOSDataDetect]):
    """Class to manage fetching AirOS status data from single endpoint."""

    config_entry: AirOSConfigEntry

    def __init__(
        self,

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Confirm the device is powered on and its web UI loads at the configured address.
2. Ping the device or curl its web interface from the Home Assistant host to rule out network/firewall issues.
3. Reserve the device IP in DHCP or correct the host in the config entry.
4. If timeouts dominate, reduce network load or check for a flaky wireless link to the device.
5. Review logs: the underlying err message distinguishes setup vs connection vs timeout.

import asyncio

async def airos_reachable(host: str, timeout: float = 5.0) -> bool:
    try:
        _, writer = await asyncio.wait_for(asyncio.open_connection(host, 443), timeout)
        writer.close()
        return True
    except (OSError, TimeoutError):
        return False

def is_airos_connect_update_failed(err: Exception) -> bool:
    return isinstance(err, UpdateFailed) and getattr(err, "translation_key", None) == "cannot_connect"

try:
        await coordinator.async_config_entry_first_refresh()
except ConfigEntryNotReady:
    # UpdateFailed during first refresh becomes NotReady: HA retries with backoff
    raise

When it happens

Trigger: airos_device.login() or the update method raises AirOSConnectionSetupError (HTTP session/aiohttp client setup failure), AirOSDeviceConnectionError (device refused/dropped the connection), or TimeoutError (request exceeded the client timeout).

Common situations: Device offline or powered off, wrong host/port in config, firewall blocking the management IP, slow device under load causing timeouts, or DNS resolution failure for the configured hostname.

Related errors

• Unable find multi-factor auth module: {mfa_module_id}
• update_error
• Failed to communicate with device.
• Failed to connect
• Data incomplete or missing

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