ZHA Event Structure Changed After Home Assistant Upgrade 2025.5.1 (unique_id Added _CLIENT Suffix)

[vangelis86]

The problem

Description: After upgrading Home Assistant, the ZHA event structure has changed, particularly the unique_id format. A _CLIENT suffix has been added to the unique_id, which was not present before. This change might affect automations or integrations that rely on the previous format.

Example Before Upgrade:

device_ieee: 38:5b:44:ff:fe:a7:cc:69 unique_id: 38:5b:44:ff:fe:a7:cc:69:1:0x0006 device_id: 599ca536847a7057b0e50962a991a792 endpoint_id: 1 cluster_id: 6 command: "on" args: [] params: {}

Example After Upgrade:

device_ieee: 38:5b:44:ff:fe:a7:cc:69 unique_id: 38:5b:44:ff:fe:a7:cc:69:1:0x0006_CLIENT device_id: 599ca536847a7057b0e50962a991a792 endpoint_id: 1 cluster_id: 6 command: "on" args: [] params: {}

What version of Home Assistant Core has the issue?

2025.5.1

What was the last working version of Home Assistant Core?

2025.4

What type of installation are you running?

Home Assistant OS

Integration causing the issue

zha

Link to integration documentation on our website

https://www.home-assistant.io/integrations/zha/

Diagnostics information

No response

Example YAML snippet

Anything in the logs that might be useful for us?

Additional information

No response

[home-assistant[bot]]

Hey there @dmulcahey, @adminiuga, @puddly, @thejulianjes, mind taking a look at this issue as it has been labeled with an integration (zha) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of zha can trigger bot actions by commenting:

• @home-assistant close Closes the issue.
• @home-assistant rename Awesome new title Renames the issue.
• @home-assistant reopen Reopen the issue.
• @home-assistant unassign zha Removes the current integration label and assignees on the issue, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the issue.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the issue.

_{^{(message by CodeOwnersMention)}}

---

zha documentation zha source _{^{(message by IssueLinks)}}

[puddly]

Do you have an automation that relies on unique_id?

Unfortunately, unique_id: 38:5b:44:ff:fe:a7:cc:69:1:0x0006 was not unique in 2025.4.0: devices that had both client and server OnOff clusters on the same endpoint generated events that could not be distinguished. Even now, the unique_id does not take into account the command ID or arguments.

[jjvandenberg]

Same issue overhere, Zigbee wallswitches that have worked for years, are now broken and needed to add _CLIENT to the id:

unique_id: a4:c1:38:ff:f3:0d:c3:be:2:0x0006_CLIENT

[puddly]

I'll see if we can add something to revert the behavior for these events. This format will change in the future but this was not something that should have changed in a visible way.

[jjvandenberg]

even worse: the _CLIENT addition is needed on some switches while other switches (same model) do NOT need it. Have to check all wall switches now.

[tomasbedrich]

Can we perhaps add it to release notes? I am reading the Backward-incompatible changes section thoroughly exactly for this reason and there was no mention about unique_id change.

[sircoynie]

This has broken all my ZHA - has anyone found a way of fixing this?

[tomasbedrich]

Workaround is maybe to switch your automation event triggers from this:

unique_id: 00:1f:ee:00:00:00:9b:57:1:0x0006
command: toggle

to this:

device_ieee: 00:1f:ee:00:00:00:9b:57
endpoint_id: 1
cluster_id: 6
command: toggle