home-assistant/core · error · HomeAssistantError

The bond API returned an error calling set_brightness_belief

Error message

The bond API returned an error calling set_brightness_belief for {self.entity_id}.  Code: {ex.status}  Message: {ex.message}

What it means

Raised by BondBaseLight.async_set_brightness_belief when Action.set_brightness_belief(round(brightness*100/255)) fails with a ClientResponseError. The 0-255 HA brightness is converted to a 0-100 Bond brightness first; the message includes the HTTP status and API message text.

Source

Thrown at homeassistant/components/bond/light.py:94

    """Representation of a Bond light."""

    _attr_color_mode = ColorMode.ONOFF
    _attr_supported_color_modes = {ColorMode.ONOFF}

    async def async_set_brightness_belief(self, brightness: int) -> None:
        """Set the belief state of the light."""
        if not self._device.supports_set_brightness():
            raise HomeAssistantError("This device does not support setting brightness")
        if brightness == 0:
            await self.async_set_power_belief(False)
            return
        try:
            await self._bond.action(
                self._device_id,
                Action.set_brightness_belief(round((brightness * 100) / 255)),
            )
        except ClientResponseError as ex:
            raise HomeAssistantError(
                "The bond API returned an error calling set_brightness_belief for"
                f" {self.entity_id}.  Code: {ex.status}  Message: {ex.message}"
            ) from ex

    async def async_set_power_belief(self, power_state: bool) -> None:
        """Set the belief state of the light."""
        try:
            await self._bond.action(
                self._device_id, Action.set_light_state_belief(power_state)
            )
        except ClientResponseError as ex:
            raise HomeAssistantError(
                "The bond API returned an error calling set_light_state_belief for"
                f" {self.entity_id}.  Code: {ex.status}  Message: {ex.message}"
            ) from ex


class BondLight(BondBaseLight, BondEntity, LightEntity):

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Read Code: in the message — 401 → re-authenticate; 404 → reload integration after re-adding device in Bond app; 5xx → retry.
  2. Verify the device still exists in the Bond app with the same device_id.
  3. Update integration + hub firmware if 400s persist on a brightness-capable light.
Defensive patterns

Strategy: try-catch

Try / catch

try:
    await light.async_set_brightness_belief(brightness)
except HomeAssistantError as err:
    status = parse_code(str(err))  # extract 'Code: NNN'
    if status == 401: trigger_reauth()
    elif status == 404: reload_integration()

Prevention

When it happens

Trigger: Any brightness set on a Bond light while the hub replies 4xx/5xx: 401 stale token, 404 device removed, 400 device rejecting the belief despite advertising the capability.

Common situations: Token rotated in the Bond app, device deleted/re-paired (device_id changed), hub overloaded returning 5xx.

Related errors

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