fix: resolve invalid entity ID warnings by caibinqing · Pull Request #1639 · XiaoMi/ha_xiaomi_home

caibinqing · 2026-02-05T19:03:47Z

Update

HA 2026.2.1 已修复此问题，将限制放宽到 2027.2.0

此 PR 仍有价值，这里提供了一种迁移到合法 unique_id 的方案。

The current warning:

Detected that custom integration 'xiaomi_home' sets an invalid entity ID: 'xiaomi_home.yeelink_cn_*********_lamp15_s_2_'. In most cases, entities should not set entity_id, but if they do, it should be a valid entity ID.. This will stop working in Home Assistant 2027.2.0

Why

更新到 HA 2026.2.0 之后，由于 Invalid entity ID 会导致部分实体不可用。

Fixed

这个 PR 是给那些有着大量设备、大量界面配置和自动化的用户用的。
如果只是简单更换 unique_id 的方式修，而不提供迁移步骤，会导致大量旧的配置不可用。就和之前 #972 那样。

由于目前官方还没有出解决方案，这里先简单使用 slugify_name 来处理不合法的 unique_id。

这个 PR 也包含了 #972 的代码，使用了一样的方式来实现 unique_id 的修改，
不管是 v1 还是 v2 的用户都可以直接使用，使用之后版本号会变成 3。

fix: #1627
fix: #1632
fix: #1634
fix: #1635
fix: #1636
fix: #1638

Usage

拉取这个PR的代码，重启HA
然后应该就好了，和原来一样。（不过版本号会变成3）

Caution

版本号变了之后就不能直接切回主线了，（但现在主线还没修，本来就也没法切回去）

parkghost · 2026-02-06T06:18:53Z

custom_components/xiaomi_home/miot/miot_device.py

+                              description: str) -> str:
+        return (
+            f'{ha_domain}.{self._model_strs[0][:9]}_{self.did_tag}_'
+            f'{self._model_strs[-1][:20]}_s_{siid}_{slugify_name(description)}')


Suggest adding a fallback in gen_service_entity_id when slugify_name(description) returns empty

I've confirmed it still works when empty. I'm just not sure what would make a better fallback here.

2026-02-06 15:04:08.456 ERROR (MainThread) [homeassistant.components.cover] Error adding entity xiaomi_home.lumi_cn_1049257520_hmcn02_s_2_ for domain cover with platform xiaomi_home Traceback (most recent call last): File "/usr/src/homeassistant/homeassistant/helpers/entity_platform.py", line 679, in _async_add_entities await self._async_add_entity( entity, False, entity_registry, config_subentry_id ) File "/usr/src/homeassistant/homeassistant/helpers/entity_platform.py", line 826, in _async_add_entity raise HomeAssistantError(f"Invalid entity ID: {entity.entity_id}") homeassistant.exceptions.HomeAssistantError: Invalid entity ID: xiaomi_home.lumi_cn_1049257520_hmcn02_s_2_

The entity ID ends with a trailing underscore _s_2_ because the service description is empty.

Why the description is empty

The MIoT vendor-specific spec for this device (urn:...:curtain:00007816:lumi-hmcn02:1:0000C817) returns "description": "" from the cloud API. The description_trans is correctly resolved to "Curtain" via std_lib.service_translate(), but description (used in gen_service_entity_id) remains empty.

Why HA 2026.2 rejects trailing underscores

HA 2026.2 tightened entity ID validation — IDs must match ^[a-z][a-z0-9_]*[a-z0-9]$ (cannot start or end with _). See home-assistant/core#137065. A trailing _ now raises HomeAssistantError during entity registration.

In addition, the entity ID of my cover before the update was cover.lumi_cn_1049257520_hmcn02_s_2_2

Thanks for catching that! I’m honestly not sure why my previous tests passed.

parkghost · 2026-02-06T09:00:03Z

Thanks for the update! The new commit fixes the entity_id generation for empty descriptions — devices now load correctly.

However, there's a migration gap for users who deployed the previous version of this PR.

Problem

Since the old code had slugify_name("") == "", the v2→v3 migration found the old and new unique_ids identical and skipped the update. After upgrading to the new code, gen_service_entity_id now omits the suffix entirely for empty slugs, but the config entry is already version 3 so the migration won't run again.

This causes a unique_id mismatch:

Integration generates: xiaomi_home.lumi_cn_1049257520_hmcn02_s_2
Registry still has: xiaomi_home.lumi_cn_1049257520_hmcn02_s_2_ (trailing underscore)

HA can't find the existing entity and creates a new one, orphaning the old entity_id (including any HA-generated dedup suffix).

Observed Result

What I observed on my system after upgrading:

	entity_id	unique_id	created_at
Old	`cover.lumi_cn_1049257520_hmcn02_s_2_2`	`xiaomi_home.lumi_cn_1049257520_hmcn02_s_2_`	2025-07-24
New (freshly created)	`cover.lumi_cn_1049257520_hmcn02_s_2`	`xiaomi_home.lumi_cn_1049257520_hmcn02_s_2`	2026-02-06

Suggestion

Add a fallback migration that also checks for stale v2-format unique_ids when the config entry is already version 3.

caibinqing · 2026-02-06T12:34:43Z

Thanks for the update! The new commit fixes the entity_id generation for empty descriptions — devices now load correctly.

However, there's a migration gap for users who deployed the previous version of this PR.

Problem

Since the old code had slugify_name("") == "", the v2→v3 migration found the old and new unique_ids identical and skipped the update. After upgrading to the new code, gen_service_entity_id now omits the suffix entirely for empty slugs, but the config entry is already version 3 so the migration won't run again.

This causes a unique_id mismatch:

Integration generates: xiaomi_home.lumi_cn_1049257520_hmcn02_s_2

Registry still has: xiaomi_home.lumi_cn_1049257520_hmcn02_s_2_ (trailing underscore)

HA can't find the existing entity and creates a new one, orphaning the old entity_id (including any HA-generated dedup suffix).

Observed Result

What I observed on my system after upgrading:

entity_id unique_id created_at
Old cover.lumi_cn_1049257520_hmcn02_s_2_2 xiaomi_home.lumi_cn_1049257520_hmcn02_s_2_ 2025-07-24
New (freshly created) cover.lumi_cn_1049257520_hmcn02_s_2 xiaomi_home.lumi_cn_1049257520_hmcn02_s_2 2026-02-06

Suggestion

Add a fallback migration that also checks for stale v2-format unique_ids when the config entry is already version 3.

This is getting a bit messy. Does this mean we'll need v4?

parkghost · 2026-02-06T15:05:59Z

In short, when HA encounters conflicts when generating entity_id, it automatically adds a serial number (_2, _3, ...) to the end of the entity_id.

Given my device's configuration, I'm unsure why these conflicts occurred; perhaps a reinstallation caused them.

As for whether the version number should be v4, it depends on whether there is a need to resolve the migration of conflicting entity_ids, and how many people have pulled this PR (I haven't encountered this issue; I've already handled it manually).

By the way, the HA official team has relaxed the restrictions until 2027.2.0:

home-assistant/core#162425

Thanks for the update! The new commit fixes the entity_id generation for empty descriptions — devices now load correctly.
However, there's a migration gap for users who deployed the previous version of this PR.

Problem

Since the old code had slugify_name("") == "", the v2→v3 migration found the old and new unique_ids identical and skipped the update. After upgrading to the new code, gen_service_entity_id now omits the suffix entirely for empty slugs, but the config entry is already version 3 so the migration won't run again.
This causes a unique_id mismatch:

Integration generates: xiaomi_home.lumi_cn_1049257520_hmcn02_s_2

Registry still has: xiaomi_home.lumi_cn_1049257520_hmcn02_s_2_ (trailing underscore)

HA can't find the existing entity and creates a new one, orphaning the old entity_id (including any HA-generated dedup suffix).

Observed Result

What I observed on my system after upgrading:
entity_id unique_id created_at
Old cover.lumi_cn_1049257520_hmcn02_s_2_2 xiaomi_home.lumi_cn_1049257520_hmcn02_s_2_ 2025-07-24
New (freshly created) cover.lumi_cn_1049257520_hmcn02_s_2 xiaomi_home.lumi_cn_1049257520_hmcn02_s_2 2026-02-06

Suggestion

Add a fallback migration that also checks for stale v2-format unique_ids when the config entry is already version 3.

This is getting a bit messy. Does this mean we'll need v4?

caibinqing · 2026-02-06T15:28:43Z

@parkghost 我不太想继续增加复杂度，毕竟这个中间版本也只存在了几个小时。

这里我提供一个手动操作方法来帮助 拉取过这个PR初始提交(372a579) 的用户，迁移剩下的几个没有description的实体。

如果你又拉取了最新提交(9159a98)，导致已经产生重复实体的情况，那么首先要把这些新建出来的实体删掉，参考上面的例子就是 created_at 2026-02-06 的那些。

把 xiaomi_home 的版本回退到我这个PR最开始的提交 372a579
建议把HA版本回退到 2026.1（方便批量筛选），重启HA
在实体列表里批量筛选”不再提供“的实体，确认一下它们都是那些后续新建出来不要的，全选-右上角三个点-删除所选项。

这样就相当于回到了前一个有点小问题的v3，接下来要手动把版本号改到2，然后重跑一下新的2->3迁移。

打开 /config/.storage/core.config_entries 搜索 xiaomi_home 应该能看到后面有个 "version":3，把 3 改成 2，保存文件
更新 xiaomi_home 到我这个PR的最新提交(9159a98)
重启HA（也可以同时升级回 2026.2）

应该就好了

caibinqing · 2026-02-06T15:44:40Z

In short, when HA encounters conflicts when generating entity_id, it automatically adds a serial number (_2, _3, ...) to the end of the entity_id.

Given my device's configuration, I'm unsure why these conflicts occurred; perhaps a reinstallation caused them.

As for whether the version number should be v4, it depends on whether there is a need to resolve the migration of conflicting entity_ids, and how many people have pulled this PR (I haven't encountered this issue; I've already handled it manually).

By the way, the HA official team has relaxed the restrictions until 2027.2.0:

home-assistant/core#162425

Glad to see the HA official team relaxed the restrictions; looks like I was just a bit too early with this PR!

parkghost · 2026-02-06T15:57:27Z

@parkghost 我不太想继续增加复杂度，毕竟这个中间版本也只存在了几个小时。

这里我提供一个手动操作方法来帮助 拉取过这个PR初始提交(372a579) 的用户，迁移剩下的几个没有description的实体。

如果你又拉取了最新提交(9159a98)，导致已经产生重复实体的情况，那么首先要把这些新建出来的实体删掉，参考上面的例子就是 created_at 2026-02-06 的那些。

把 xiaomi_home 的版本回退到我这个PR最开始的提交 372a579

建议把HA版本回退到 2026.1（方便批量筛选），重启HA

在实体列表里批量筛选”不再提供“的实体，确认一下它们都是那些后续新建出来不要的，全选-右上角三个点-删除所选项。

这样就相当于回到了前一个有点小问题的v3，接下来要手动把版本号改到2，然后重跑一下新的2->3迁移。

打开 /config/.storage/core.config_entries 搜索 xiaomi_home 应该能看到后面有个 "version":3，把 3 改成 2，保存文件

更新 xiaomi_home 到我这个PR的最新提交(9159a98)

重启HA（也可以同时升级回 2026.2）

应该就好了

問題的原因與解決方式我並沒有深入研究，主要是回報我遇到的問題狀況，請仍以您的判斷為準

由於 HA 官方目前僅將限制放寬至 2027.2.0，未來 ha_xiaomi_home 仍可能需要進行遷移處理，但不確定是否適合在這個 PR 中一併處理

謝謝您的協助

1a2a3a1q2s3c · 2026-02-06T17:54:36Z

I don’t understand Chinese. Can we update HA already to 2026.2?

caibinqing · 2026-02-07T02:24:08Z

I don’t understand Chinese. Can we update HA already to 2026.2?

Yes, you can update to 2026.2.1 now. (not 2026.2.0)

caibinqing added 4 commits April 7, 2025 10:54

fix: add migration step for config entry

7c0caa9

fix pylint

506bd9f

Merge branch 'migrate' into migrate2026.2

ffd90a0

fix: migrate unique_id for 2026.2

372a579

parkghost reviewed Feb 6, 2026

View reviewed changes

fix: fix invalid entity ID when slugify_name returns empty

9159a98

caibinqing force-pushed the migrate_2026.2 branch from 6ffeb55 to 9159a98 Compare February 6, 2026 08:16

caibinqing changed the title ~~fix: migrate unique_id for 2026.2~~ fix: resolve invalid entity ID warnings Feb 7, 2026

Conversation

caibinqing commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Update

Why

Fixed

Usage

Caution

Uh oh!

parkghost Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

caibinqing Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

parkghost Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

caibinqing Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

parkghost commented Feb 6, 2026

Problem

Observed Result

Suggestion

Uh oh!

caibinqing commented Feb 6, 2026

Problem

Observed Result

Suggestion

Uh oh!

parkghost commented Feb 6, 2026

Problem

Observed Result

Suggestion

Uh oh!

caibinqing commented Feb 6, 2026

Uh oh!

caibinqing commented Feb 6, 2026

Uh oh!

parkghost commented Feb 6, 2026

Uh oh!

1a2a3a1q2s3c commented Feb 6, 2026

Uh oh!

caibinqing commented Feb 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

caibinqing commented Feb 5, 2026 •

edited

Loading

parkghost Feb 6, 2026 •

edited

Loading