WTH What's the point of unique_id

Without unique_id set everything works without problem. With little exception.
Recently I found that card opened after clicking on gear icon found on an mqtt ligh card shows following message: “This entity does not have a unique ID”.

Wait a moment. Is it true? The entity has unique ID automatically generated from name, right?

  - platform: mqtt
    schema: template
    name: "Hall Floor 2"

Then I can see light.hall_floor_2 in several places in HA.
Isn’t it Entity ID requested in the mentioned message?
I also know it is ensured by HA that this ID is always unique (if not, HA adds number at the end of entity id)

Then I did a search through the forum and found that I need to set unique_id attribute. I did that.

  - platform: mqtt
    schema: template
    name: "Hall Floor 2"
    unique_id: hall_floor_2_cct

TBH I believed that it will give ability to set name to friendly name, while Entity ID will be defined by unique_id.
Guess what name is used for entity id after the change.
You are wrong (some of you are right though). It’s still light.hall_floor_2.

WTH is going on?

Ahh. after removing unique_id from ligh (and restarting HA) one cold expect that everything should back to previous state.
But it’s again not true. Such entity in lovelace will appear unavailable, and opened entity popup will show info that it is orphant and should be removed from the system. IMO it deserves another WTH.

After agreeing on removing orphant, and restarting HA finally we are at the begining. This behaviour is really awkward.

light.hall_floor_2 is not the unique ID being referred to. You cannot set the unique ID the way you appear to be trying to. The unique ID being referred to comes from a config entry, YAML created entities don’t have one.

The message should be adjusted in my opinion, its rather confusing. What its really trying to tell you is because this entity comes from YAML and not from a config entry its not UI-configurable. Generally only entities created from UI-configurable integrations or via discovery get a config entry (and therefore a unique ID) and become UI-configurable.

I’m keeping my fingers crossed that I got this right since I’m not an expert on HA internals. Hopefully someone more knowledgeable will come correct me if I messed something up. That’s my understanding though.

1 Like

It does make sense what you are saying.
So those are two independent identifiers, while unique_id is accidently called “entity id” in the message.


  1. why HA needs 2 unique identifiers for single entity. Isn’t it antipattent?
  2. why it’s impossible to set entity id for mqtt light (to be not inheritted from name attribute)

Right I probably should’ve explained that more. So each entity ID is unique in a given runtime but it may not uniquely identify the same device all the time. Lets say for example that you changed the name from Hall Floor 2 to Hall Floor 3 and restarted. Now the entity ID for that same device becomes light.hall_floor_3 and light.hall_floor_2 is a different device entirely, it no longer identifies the same device. This can also occur if you make another light and also name it Hall Floor 2, one becomes light.hall_floor_2 and hte other light.hall_floor_2_2 depending on which happens to be registered first.

Config entries on the other hand are tied to the physical device itself. No matter what the name or entity ID happens to be in a given runtime the unique ID tied to the config entry remains the same. Which is why one of the thing you can configure for those devices is the entity ID itself, it becomes changeable.

As for your second point, that’s really just a choice of that integration. Some integrations allow you to define the entity ID in the YAML config and some make it for you from the name. It’s really the choice of the integration to my knowledge.

Yeah I got it.
Pitty is, that lovelace, while showing entitites still works with entity_id rather than unique_id.
So changing the first ends with “entity not available” even there is unique_id which could be used for identifying the entity.
Or I should say: it works with entity_id in some cases, requiring unique_id in others.
I believe it must be for something, but from user point of view it adds no value IMO. It’s rather confusing.

Some integrations allow you to define the entity ID in the YAML config and some make it for you from the name.
Which makes HA pretty inconsistent in that area.

Thank you for exaplanations.

1 Like

Curiously, you can for example specify unique_id on MQTT sensor entities, but not input_booleanss.

I’m also having a similar problem, when using lovelace I would like to be able to set the mqtt entity_id to something meaningful and unique, but have the name as the display name. There doesn’t seem to be a way to do this, but interestingly if I create an element using mqtt discovery, then update the friendly name then the entity_id remains the same as the initial value even though the name has changed.
It would make so much more sense if I could define the entity_id on the sensor (ideally via discovery) or if the unique_id was actually used as the entity id.

The concept of unique_id is still confusing to me, especially the conceptual difference with the entity_id.

Its existence seems to imply you could have 2 identical entity id, and that they would differentiated by unique_id? I’m pretty sure that would be problematic, if even possible.

Or is it purely a technical id? But then why not just use the entity_id? That would probably be less confusing, considering lacking one percolates to the UI with some messages when trying to manage entities…

you cannot have two identical entity_id neither.
Those can somehow exist in configuration but HA will rename on of them adding numering suffix. So in runtime entity_id is unique.

The reason of existance of unique_id is still not clear despite questions asked multiple times. It has been said it’s for Lovelace. If it’s really the only reason, then imo it’s bad dessign decission. Taking however into consideration how integrations are inconsistent in the matter of entity_id, maybe it’s the first step to provide real, consistent and the only one identifier.
Unfortunately devs are not transparent in their decissions so this is my quess only

1 Like

The difference is really quite simple but also technical. In the early days of Home Assistant, there were only entity id. It was generated automatically by combining a domain (e.g. light or switch) and generally a “slugified” name (e.g. “Living Room Window” -> living_room_window). So a light in the living room window would become light.living_room_window for instance. There are a few problems with this however.

If you have two “things” that happened to generate the same entity id, you would get one with the expected entity id and another one with _2 appended to it. Depending on which got initialized first, you wouldn’t know which one is which. It wouldn’t necessarily be possible to change that either. Another thing is that you bind some configuration settings to an entity id, rather than a device. So if you change for instance the icon or another attribute, those would still apply to the entity even if you switched hardware (and used the same name, so the same entity id was generated). That might be expected behavior, but not necessarily.

To kind of fix this, Home Assistant needs a way to map internal configuration to a particular device without residing to things like name. Entity id and name should not need to have any correlation since you might want to use English names for entity id, but a localized name for presentation. That is what unique_id is for. It is a unique identifier that identifies one specific device. Examples in this case are serial numbers, MAC addresses, or some other kind of unique identifier provided by the device. An IP address is a good example of the opposite, as it’s not uncommon that a device can change IP address due to DHCP lease. Such a thing must not change unique_id.

By having an identifier that is unique per device, Home Assiatant can store configuration for that specific device. That’s why you can change entity id for an entity that supports unique_id, but not for one that doesn’t. Other things like icons, unit of measurement and so on can be applied in the same way.

As a last note… You never deal with unique_id yourself. It’s used internally by Home Assistant. Unless you develop things with/for Home Assistant, you don’t need to know what it is.


Thanks, that make more sense.

What still evades me a little bit is why a random unique_id is not autogenerated for those entities not having one rather than having those “This entity does not have a unique ID” in the UI.
You say "You never deal with unique_id but this forces you to :wink:

On a side node, my use case is MQTT discovery. If somehow you don’t attach a unique_id, you get to this point, so even as a plain user, you have to deal with it.


Not you what you meant, but info about not existent unique id appears in Lovelace being shown to regular users. And users/ha admins want to solve it. in case of some integrations (mqtt for example) you have to add unique id manually to make the mentioned message dissapear being replaced by lovelace feature

You cannot generate a unique_id, it must come from the device. If you have a local config with a random id in Home Assistant, how would you map that to a physical device unless the device provides unique id by itself in some way? A few integrations have exceptions, that allow you to provide unique_id in the YAML config, but that’s very special cases and do not map to a physical device.

What I really mean is that you never use the value of unique_id in any way, e.g. when referring to an entity in automation. Generally integrations should provide it and you should not have to bother. But there are of course exceptions (it’s inevitable), like you mention with MQTT. Since MQTT is close to development in some sense, I would still see that as a very special case. There are also integrations that have just not added support for it yet, or can’t because there’s no unique id available.


I mean it more in the sense that you don’t have to care about the value of unique_id as it’s not used when writing automations or referring to an entity, other than internally in Home Assistant. As I just wrote in my previous post, there are cases where unique_id is not available (maybe no unique identifier exists or it has not been implemented yet), and that of course creates issues. The fact that you have to provide it for MQTT is just because MQTT itself is just a general protocol. It does not have a notion of “unique id” in the sense that Home Assistant needs, so you have to provide it yourself. For most protocols there are however, which makes the experience seamlessly for the user.

1 Like

I have exactly the same problem with mqtt discovery too. I would like to be able to specify my entity_id as part of the discovery creation. I know the value will be unique as I am controlling it.
With the idea I create a Group, then add all these entities to the group so it turns up in lovelace as a single panel. As in Group you need to specify entities not unique_ids.

It might be worth adding the ability to set the entity_id in mqtt_discovery, and also support referencing unqiue_id in a group.