home-assistant/core · error · HomeAssistantError

communication_error

communication_error

Error message

An error occurred while communicating with the Airgradient device: {error}

What it means

Raised by the exception_handler decorator used on AirGradient entity service methods (e.g. setting fan speed or configuration attributes). When the underlying library call raises AirGradientConnectionError, it is re-raised as HomeAssistantError with translation key communication_error, so the user sees a clean, translated message in the service-call UI instead of a raw traceback.

Source

Thrown at homeassistant/components/airgradient/entity.py:49

            serial_number=coordinator.serial_number,
            sw_version=measures.firmware_version,
            connections={(dr.CONNECTION_NETWORK_MAC, coordinator.serial_number)},
        )


def exception_handler[_EntityT: AirGradientEntity, **_P](
    func: Callable[Concatenate[_EntityT, _P], Coroutine[Any, Any, Any]],
) -> Callable[Concatenate[_EntityT, _P], Coroutine[Any, Any, None]]:
    """Decorate AirGradient calls to handle exceptions.

    A decorator that wraps the passed in function, catches AirGradient errors.
    """

    async def handler(self: _EntityT, *args: _P.args, **kwargs: _P.kwargs) -> None:
        try:
            await func(self, *args, **kwargs)
        except AirGradientConnectionError as error:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="communication_error",
                translation_placeholders={"error": str(error)},
            ) from error

        except AirGradientError as error:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="unknown_error",
                translation_placeholders={"error": str(error)},
            ) from error

    return handler

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Verify device reachability from the HA host (ping / curl the device)
Correct the host in the AirGradient config entry via reconfigure
Fix network segmentation/firewall rules so HA can reach the device
Retry the service call once the device responds

Defensive patterns

Strategy: try-catch

Try / catch

from homeassistant.exceptions import HomeAssistantError

try:
    await hass.services.async_call(DOMAIN, "set_fan_speed", {...}, blocking=True)
except HomeAssistantError as err:
    # translation key communication_error: device unreachable; check host/network
    _LOGGER.warning("AirGradient command failed: %s", err)

Prevention

Verify device reachability before running automations that control it
Alert on the entity being unavailable rather than catching per-call
Use static IP/DNS for the device

When it happens

Trigger: Any entity action (config/fan/number services) on an AirGradient entity where the HTTP request to the device fails at the transport level: connection refused, timeout, DNS failure — anything the airgradient library classifies as AirGradientConnectionError.

Common situations: Pressing a control button while the device is powered off or unreachable, wrong IP after network changes, or HA and device on separated VLANs.

Related errors

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