home-assistant/core · warning · UpdateFailed

Airtouch connection issue

Error message

Airtouch connection issue

What it means

UpdateFailed raised by the AirTouch 4 coordinator when UpdateInfo() completes without throwing but the client's Status flag is not AirTouchStatus.OK — the library signals a soft failure (bad frame, checksum, or partial response) rather than an exception. All Airtouch entities go unavailable until a poll succeeds with OK status.

Source

Thrown at homeassistant/components/airtouch4/coordinator.py:43

        self, hass: HomeAssistant, entry: AirTouch4ConfigEntry, airtouch: AirTouch
    ) -> None:
        """Initialize global Airtouch data updater."""
        self.airtouch = airtouch

        super().__init__(
            hass,
            _LOGGER,
            config_entry=entry,
            name=DOMAIN,
            update_interval=SCAN_INTERVAL,
        )

    @override
    async def _async_update_data(self):
        """Fetch data from Airtouch."""
        await self.airtouch.UpdateInfo()
        if self.airtouch.Status != AirTouchStatus.OK:
            raise UpdateFailed("Airtouch connection issue")
        return {
            "acs": [
                {"ac_number": ac.AcNumber, "is_on": ac.IsOn}
                for ac in self.airtouch.GetAcs()
            ],
            "groups": [
                {
                    "group_number": group.GroupNumber,
                    "group_name": group.GroupName,
                    "is_on": group.IsOn,
                }
                for group in self.airtouch.GetGroups()
            ],
        }

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Check the AirTouch unit is powered and its local app connects fine.
2. Verify the IP configured for the integration still points at the controller (DHCP changes).
3. Reduce network interference or move the HA host closer to the unit.
4. Reload the integration to re-establish the session if status stays non-OK.
5. If persistent, capture whether Status cycles between OK and error to spot a polling-rate issue.

from airtouch4pyapi import AirTouchStatus

async def airtouch_healthy(airtouch) -> bool:
    await airtouch.UpdateInfo()
    return airtouch.Status == AirTouchStatus.OK

def is_airtouch_connection_issue(err: Exception) -> bool:
    return isinstance(err, UpdateFailed) and str(err) == "Airtouch connection issue"

try:
    await airtouch.UpdateInfo()
    if airtouch.Status != AirTouchStatus.OK:
        # soft failure: status flag instead of exception; reload integration to reset session
        raise UpdateFailed("Airtouch connection issue")
except UpdateFailed:
    await hass.config_entries.async_reload(entry.entry_id)

When it happens

Trigger: self.airtouch.UpdateInfo() returns with Status != OK: the AirTouch A4 controller responded with corrupted/unexpected data, the UDP/TCP session state desynced, or the unit is briefly unreachable and the library reflects it in status rather than raising.

Common situations: Network congestion or WiFi dropouts to the AirTouch unit, the controller rebooting or its app connected simultaneously causing session conflicts, or firmware quirks after power events.

Related errors

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

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