ZHA fails to load when `ClusterType.Client` is used in v2 Quirk

[tr4nt0r]

Bug description

The log outputs this error:

Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/components/logbook/processor.py", line 259, in _humanify
    data = describe_event(event_cache_get(row))
  File "/usr/src/homeassistant/homeassistant/components/zha/logbook.py", line 44, in async_describe_zha_event
    zha_device = async_get_zha_device_proxy(
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~^
        hass, event.data[ATTR_DEVICE_ID]
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ).device
    ^
  File "/usr/src/homeassistant/homeassistant/components/zha/helpers.py", line 1060, in async_get_zha_device_proxy
    zha_gateway_proxy = get_zha_gateway_proxy(hass)
  File "/usr/src/homeassistant/homeassistant/components/zha/helpers.py", line 1039, in get_zha_gateway_proxy
    raise ValueError("No gateway object exists")
ValueError: No gateway object exists

Steps to reproduce

This V2 Quirk caused the error:

• Add Telink devices with custom ZigbeeTlc firmware quirk zha-device-handlers#3719

In the quirk an out cluster is replaced, but when creating a number input for this cluster ZHA integration fails to load. When commenting out ClusterType.Client, ZHA will load again but will not create the entities as it cannot find the cluster

(
    QuirkBuilder("MiaMiaoCe", "MHO-C401N-z")
    .applies_to("Xiaomi", "LYWSD03MMC-z")
    .replaces(CustomUserInterfaceCluster, cluster_type=ClusterType.Client)
    .number(
        CustomUserInterfaceCluster.AttributeDefs.temperature_offset.name,
        CustomUserInterfaceCluster.cluster_id,
        ClusterType.Client,
        min_value=-327.67,
        max_value=327.67,
        step=0.01,
        unit=UnitOfTemperature.CELSIUS,
        translation_key="temperature_offset",
        fallback_name="Temperature offset",
        multiplier=100
    )
    .number(
        CustomUserInterfaceCluster.AttributeDefs.humidity_offset.name,
        CustomUserInterfaceCluster.cluster_id,
        ClusterType.Client,
        min_value=-327.67,
        max_value=327.67,
        step=0.01,
        # unit=PERCENTAGE,
        translation_key="temperature_offset",
        fallback_name="Temperature offset",
        multiplier=100
    )
    .add_to_registry()
)

Expected behavior

ZHA loads successfully and creates the number entities

[TheJulianJES]

Is there more in the logs? "No gateway object exists" happens because ZHA didn't load correctly, so something must have happened earlier on.

[TheJulianJES]

Also, a "client" cluster means that you generally can't set any values it on. It's really intended to only output to the coordinator/other bound devices.
Can you set the values correctly using the the debug "Manage Zigbee device / Clusters" UI?
Oh, and can you also attach the signature from the device without using the quirk?

[tr4nt0r]

yes, reading and setting values works.

{
  "node_descriptor": {
    "logical_type": 2,
    "complex_descriptor_available": 0,
    "user_descriptor_available": 0,
    "reserved": 0,
    "aps_flags": 0,
    "frequency_band": 8,
    "mac_capability_flags": 128,
    "manufacturer_code": 4417,
    "maximum_buffer_size": 74,
    "maximum_incoming_transfer_size": 404,
    "server_mask": 10752,
    "maximum_outgoing_transfer_size": 404,
    "descriptor_capability_field": 0
  },
  "endpoints": {
    "1": {
      "profile_id": "0x0104",
      "device_type": "0x0302",
      "input_clusters": [
        "0x0000",
        "0x0001",
        "0x0003",
        "0x0020",
        "0x0402",
        "0x0405"
      ],
      "output_clusters": [
        "0x0019",
        "0x0204"
      ]
    }
  },
  "manufacturer": "Xiaomi",
  "model": "LYWSD03MMC-z",
  "class": "zigpy.device.Device"
}

[tr4nt0r]

Found this in the logs, otherwise nothing suspect

2025-01-19 02:53:40.094 DEBUG (MainThread) [zha.zigbee.endpoint] Creating cluster handler for cluster id: 0 class: <class 'zha.zigbee.cluster_handlers.general.BasicClusterHandler'>
2025-01-19 02:53:40.094 DEBUG (MainThread) [zha.zigbee.endpoint] Creating cluster handler for cluster id: 1 class: <class 'zha.zigbee.cluster_handlers.general.PowerConfigurationClusterHandler'>
2025-01-19 02:53:40.094 DEBUG (MainThread) [zha.zigbee.endpoint] Creating cluster handler for cluster id: 3 class: <class 'zha.zigbee.cluster_handlers.general.IdentifyClusterHandler'>
2025-01-19 02:53:40.094 DEBUG (MainThread) [zha.zigbee.endpoint] Creating cluster handler for cluster id: 32 class: <class 'zha.zigbee.cluster_handlers.general.PollControlClusterHandler'>
2025-01-19 02:53:40.094 DEBUG (MainThread) [zha.zigbee.endpoint] Creating cluster handler for cluster id: 1026 class: <class 'zha.zigbee.cluster_handlers.measurement.TemperatureMeasurementClusterHandler'>
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.zigbee.endpoint] Creating cluster handler for cluster id: 1029 class: <class 'zha.zigbee.cluster_handlers.measurement.RelativeHumidityClusterHandler'>
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] Discovering entities for endpoint: a4:c1:38:ba:35:bf:1b:f6-1
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] 'button' platform -> 'IdentifyButton' using ['identify']
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] 'sensor' platform -> 'Battery' using ['power']
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] 'sensor' platform -> 'Temperature' using ['temperature']
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] 'sensor' platform -> 'RSSISensor' using ['basic']
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] 'sensor' platform -> 'LQISensor' using ['basic']
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] 'sensor' platform -> 'Humidity' using ['humidity']
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] 'update' platform -> 'FirmwareUpdateEntity' using ['ota']
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] Discovering entities for device: a4:c1:38:ba:35:bf:1b:f6-Xiaomi LYWSD03MMC-z
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.discovery] Attempting to discover quirks v2 entities for device: a4:c1:38:ba:35:bf:1b:f6-Xiaomi LYWSD03MMC-z
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.helpers] stopping global updater
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.helpers] global updater stopped
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.helpers] stopping device availability checker
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.helpers] device availability checker stopped
2025-01-19 02:53:40.095 DEBUG (MainThread) [zha.application.gateway] Shutting down ZHA ControllerApplication
2025-01-19 02:53:40.095 DEBUG (MainThread) [zigpy_znp.api] Sending request: SYS.ResetReq.Req(Type=<ResetType.Soft: 1>)
2025-01-19 02:53:40.096 DEBUG (MainThread) [zigpy_znp.api] Request has no response, not waiting for one.
2025-01-19 02:53:40.096 DEBUG (MainThread) [zigpy.serial] Waiting for serial port to close

2025-01-19 02:44:28.340 DEBUG (MainThread) [homeassistant.components.zha] Failed to set up ZHA
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/components/zha/__init__.py", line 151, in async_setup_entry
    await zha_gateway.async_initialize()
  File "/usr/local/lib/python3.13/site-packages/zha/application/gateway.py", line 275, in async_initialize
    await self._async_initialize()
  File "/usr/local/lib/python3.13/site-packages/zha/application/gateway.py", line 264, in _async_initialize
    self.load_devices()
    ~~~~~~~~~~~~~~~~~^^
  File "/usr/local/lib/python3.13/site-packages/zha/application/gateway.py", line 301, in load_devices
    zha_device = self.get_or_create_device(zigpy_device)
  File "/usr/local/lib/python3.13/site-packages/zha/application/gateway.py", line 568, in get_or_create_device
    zha_device = Device.new(zigpy_device, self)
  File "/usr/local/lib/python3.13/site-packages/zha/zigbee/device.py", line 551, in new
    discovery.DEVICE_PROBE.discover_device_entities(zha_dev)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/zha/application/discovery.py", line 200, in discover_device_entities
    self.discover_quirks_v2_entities(device)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/zha/application/discovery.py", line 271, in discover_quirks_v2_entities
    assert cluster_handler
           ^^^^^^^^^^^^^^^
AssertionError

[TheJulianJES]

Ok, so the discovery for quirks v2 entities expects a cluster handler to exist. Since there's only a UserInterfaceClusterHandler for server/input clusters but not one for client/output clusters, the discovery fails causing ZHA to not load.

I think it's still weird that it's a client/output cluster, but we should still handle this better.

---

Something else to test, what happens if you do the following (instead of .replaces):

.removes(CustomUserInterfaceCluster.id, cluster_type=ClusterType.Client)
.adds(CustomUserInterfaceCluster)  # ClusterType.Server by default

Can you still read the values as expected using the debug UI? If so, try adding back the numbers (but not with the client type).

[tr4nt0r]

That worked ^^

Also the number inputs work now :)