home-assistant/core · error · HomeAssistantError

unknown_error

unknown_error

Error message

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

What it means

The sibling branch of the AirGradient exception_handler: a non-connection AirGradientError from a library call on an entity action becomes HomeAssistantError with translation key unknown_error. Typically this means the request reached the device but the device/library rejected it — bad payload, unsupported control on this firmware, or a malformed response.

Source

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

    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

Update the AirGradient device firmware to the latest version so all control endpoints exist
Check the wrapped original error in the log to see which control call failed and what the device answered
Avoid invoking the unsupported control on this hardware model
If firmware is current, report the issue to the airgradient library maintainers with the device model

Defensive patterns

Strategy: try-catch

Try / catch

try:
    await hass.services.async_call(DOMAIN, service, data, blocking=True)
except HomeAssistantError as err:
    # unknown_error: request reached device but was rejected; inspect chained error in logs
    _LOGGER.warning("AirGradient rejected command: %s", err)

Prevention

Keep device firmware current so all control endpoints exist
Check the chained AirGradientError in logs to distinguish rejection from connectivity
Do not invoke controls unsupported by the hardware model

When it happens

Trigger: Entity service call raises a generic AirGradientError that is not AirGradientConnectionError — e.g. the firmware does not support the control being set, the API returned an error status, or response parsing failed.

Common situations: Older firmware that lacks a control endpoint the integration exposes, or a device model where a feature (e.g. fan control) is not available even though the entity was created.

Related errors

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