PSA: MQTT Name changes in 2023.8

Everyone, there will be MQTT name changes in the next release of the software. There is nothing to worry about, your names are safe. However the change caused addons like Z2M (and other MQTT integrations) to update their discovery information. As it stands, Z2M will not be able to release a version with this fix until September 2023. During that time a warning will be in your logs indicating that there is an issue. You can safely ignore this warning. As of this writing, there may also be an accompanied repair. You can also safely ignore this repair.

Once Z2M updates, the warnings will go away.

Again, during this whole transition period, your names and the default device names should not change. Please keep us informed if they do change.

As for anyone using other MQTT addons/discovery providers, please notify the upstream library about the change. Once that is done, you can safely ignore the repair and warnings until it is fixed in the upstream library.

The change states that MQTT should not provide the device name in the entity names that are attached to the device. So if your upstream MQTT provider is supplying a device name inside the entity name, they should stop providing that information. They should only provide the device name to the device, not the entity.

Here is an example log:

MQTT device name is equal to entity name in your config {'availability': [{'topic': 'zigbee2mqtt/bridge/state', 'payload_available': 'online', 'payload_not_available': 'offline'}], 'brightness': True, 'brightness_scale': 254, 'command_topic': 'zigbee2mqtt/Spots woonkamer/set', 'device': {'identifiers': ['zigbee2mqtt_0x8cf681fffe9d549f'], 'manufacturer': 'EcoDim', 'model': 'Zigbee & Z-wave dimmer (Eco-Dim.07/Eco-Dim.10)', 'name': 'Spots woonkamer', 'sw_version': '1.01', 'connections': []}, 'name': 'Spots woonkamer', 'schema': 'json', 'state_topic': 'zigbee2mqtt/Spots woonkamer', 'unique_id': '0x8cf681fffe9d549f_light_zigbee2mqtt', 'flash_time_long': 10, 'optimistic': False, 'payload_available': 'online', 'enabled_by_default': True, 'flash_time_short': 2, 'qos': 0, 'white_scale': 255, 'encoding': 'utf-8', 'color_temp': False, 'xy': False, 'rgb': False, 'color_mode': False, 'payload_not_available': 'offline', 'hs': False, 'retain': False, 'availability_mode': 'latest', 'effect': False}, this is not expected. Please correct your configuration. The entity name will be set to `null`

If you unsure about the term upstream provider, please take a moment to understand how MQTT works. A separate software will create topics that contain messages on the MQTT Broker (Your MQTT Addon), home assistant will then listen to the messages on those topics and react to changes. You have to identify the software that is creating the messages. This software is not controlled by HA. Once you determine the origin of the messages, open an issue on that software’s page explaining this change. Then you can safely ignore the warning and repair until they make changes to their software. There is nothing else you can do unless you are the provider of the messages (a developer, a mqtt yaml guru, or an automation mqtt yaml guru). So, if you don’t understand any of this, you’re not the provider of the messages. Meaning you can’t fix it, you can only notify people that a fix needs to happen. That fix will be outside HA.

And lastly, this change does not affect the auto generated entity_ids.

Final Lastly, Your devices will continue to work after the April update, even if the upstream developer doesn’t make the necessary changes. You just might have a duplicate name shown in the UI.


I saw the errors, but I’m more interested how I have to adopt my own written discovery messages.


Thanks for the heads up, i will skip this months release.


I just want to be clear: this isn’t a breaking change. The only change you will see is the warning in your logs and a possible repair (to ignore). Everything else will remain the same. Myself and a few others have been running this with Z2M and everything is working great.


Then why the change now, and not in september?


I think you’re miss understanding the change. HA made a change, Z2M is going to adapt to the change in September. As a result, there will be a log telling users to ‘contact the upstream dev’ about this change. You don’t need to do that because the developer already knows. HA is handling everything under the hood for the time being, however there will be a warning in your logs and a possible repair.


I am using the 2023.8 betas and z2m. I am not an avid log watcher, and everything is working as usual.

1 Like

The messages are in the latest beta. You’re probably on a previous one, which had some interesting naming issues. You wouldn’t catch them if you weren’t looking for it. Anyways, the latest beta fixes those little issues and puts a warning in the logs. FYI the naming issues are purely “friendly name” issues, nothing with entity_id’s or things that break automations.

Yes just got the latest beta 2023.8.0b3 and got the repairs.

My point was that z2m is working fine. Just reinforcing your assurances that nothing is actually broken.


Yes, this is true. Everything works fine, nothing will break. Just a warning message and repair you can ignore.


Maybe it would be nice to add an example of a name that is causing the error and one that would be correct?
The whole device/entity-naming is slightly confusing for someone who is not working with this 24/7, but still might have some development experience.


I’m waiting for the 2023.8 release to ask the question, the instructions on MQTT - Home Assistant are not clear to me, but the mods don’t like the beta discussed.
(I have a lot of discovered entities/devices where I create the discovery message myself)



As a greybeard dev with custom MQTT discovery code in the wild and who is not (yet) running 2023.8, the advance notice is appreciated - thanks!

EDIT: It seems the change is to concatenate Name with Entity Name, so it makes no sense to have Name = Entity Name.

To help myself understand what needs to change in my code, and possibly spread my confusion :crazy_face:, here’s an attempt to take the warning message apart:

MQTT device name is equal to entity name in your config 
  'availability': [{
    ...stuff removed...
  ...stuff removed...
  'command_topic': 'zigbee2mqtt/Spots woonkamer/set', 
  'device': {
    'identifiers': ['zigbee2mqtt_0x8cf681fffe9d549f'], 
    'manufacturer': 'EcoDim', 
    'model': 'Zigbee & Z-wave dimmer (Eco-Dim.07/Eco-Dim.10)', 
    'name': 'Spots woonkamer',                <<<===- Device NAME #1
    'sw_version': '1.01', 'connections': []
  'name': 'Spots woonkamer',                  <<<===- Entity NAME #2
  'schema': 'json', 
  'state_topic': 'zigbee2mqtt/Spots woonkamer', 
  'unique_id': '0x8cf681fffe9d549f_light_zigbee2mqtt', 
  ...stuff removed...
this is not expected. Please correct your configuration. The entity name will be set to `null`

Reading your note suggests annotation NAME #1 is fine, but annotation NAME #2 should be removed.
My guess is you can have several of the same device but each needs a unique entity name (which will be system generated) hence the warning.

The example error would give an entity called NAME 1 + NAME 2 = ‘Spots woonkamer Spots woonkamer’, which is silly. NAME #2 should be changed to 'none' or 'Light' - which is what the error is trying to communicate.

My assumption is it will be easy to search the code in GitHub for the error string and logic after release to trace the actual code (“Use the Source Luke!”).

In advance of actually running the 2023.8 release, finding the code and testing changes to my client code, the change looks simple (comment out publishing ‘name’ for the outer entity, leaving the 'device': { 'name': 'foo' }) (ensure each entity has a sensible sub-name like ‘Sensor 1’ or none), but integration testing seldom works first time!

At the least, the MQTT documentation page will need an update as the example mosquitto_pub command includes both device and entity name set to almost the same likely giving Garden garden which won’t give an error but is now silly so might be an easy first smoke test to generate the warning.

Happy software engineering,



Are you referring to what you’d need to fix? If yes… if your discovery information (or yaml configuration) is…

  - device:
      name: Zooz ZEN04
    name: Zooz ZEN04 Power

will cause the warning where this will not (and it’s how you should configure it from now on)

  - device:
      name: Zooz ZEN04
    name: Power

Otherwise you’ll get duplicate names for your entities. e.g. Zooz ZEN04 Zooz ZEN04 Power. Currently, HA under the hood removes this duplicate name during the transition period while all the upstream systems catch up.


I wonder why they don’t put something like that in the breaking changes, would be so much easier :slight_smile:


It is in the breaking changes :wink:


The whole reason I created this thread is because there will be 3087293749238438932423 people bringing up the repair and warnings in the release thread… at least I think that will happen.


That I had read, but your simple explanation of what to change is a thousand times more useful.


That is exactly what I was looking for. Thanks a lot.


I assume this be fixed under the hood also for Mosquitto broker? Only Z2M is mentioned here. Maybe the repair notification could have been modified to notify that there is really for no worries for people using xxx, yyy,… MQTT integrations.

1 Like

Well… it’s not mentioned because what you’re saying doesn’t make sense. There are no other MQTT integrations. There is only MQTT and devices that talk to MQTT. Z2M is the only upstream software (that we know of) that uses HA’s MQTT integration that is planning a fix.

That’s why this post says