[Guide] How to remove MQTT entity from Zigbee2mqtt, Mosquitto broker and Home Assisntant

The reason I’m creating this guide is that I spent hours trying to figure out an easy way to remove an MQTT device properly without uninstall Mosquitto broker or purge the whole database.

This guide applies to hassio with Zigbee2mqtt and Mosquitto broker add-on.

Unlike most other protocol where you simply click a few button to remove a device. You need to remove a device from a couple of places. In this guide, I’ll use “KitchenLight” as example.
Step 1: In hassio, go to Developer Tools - MQTT, Topic: zigbee2mqtt/bridge/config/remove, Payload: Entity ID of “KitchenLight”, then pulish. You can verify whether it’s successful by checking log in Zigbee2mqtt. It should read something like:

zigbee2mqtt:info 8/8/2019, 5:14:58 PM Successfully removed 0x00158d000312d92f
zigbee2mqtt:info 8/8/2019, 5:14:58 PM MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"device_removed","message":"0x00158d000312d92f"}'

Step 2: Download MQTT Explorer or similar app and login your MQTT server with your mqtt account specified in Zigbee2mqtt add-on. In MQTT Explorer, navigate to homeassistant - light, find the entity ID of “KitchenLight” and delete it.

Step3: Delete “KitchenLight” from Hassio’s configuration - entity registry.
Step3: Restart Zigbee2mqtt, Mosquitto broker and lastly Home Assistant.
Step4: Done, now “KitchenLight” is gone from both Zigbee2mqtt and Home Assistant’s entity registry. Step5: Thank @123 , a detailed explanation how and why this works can be found here:


This doesn´t work for me. I have some xiaomi/aqara switches that i want to remove but i can´t. I can remove switch and sensors in mqtt explorer but the entity still remains under intgrations. The switch and sensors are gone but the empty entity still remains.

This is exactly my situation aswell. I followed the guide and had the sensor and switch removed but the entity/device is still there containing nothing.
Anyone knows to get rid of this?

1 Like

Thanks for the topic! Saved me a lot of time also. :slight_smile:

All, This is how I make this work with battery powered devices…

I saw your comment that this guide is not working.
I had the same issue with battery powered sensors.
I suggest to add these 2 Steps before starting the procedure. Worked for me with Xiaomi sensors.

  • Activate Zigbee2mqtt pairing mode.
  • Put your device in pairing mode (Hold the button for 10 sec.)

Then, follow this guide from step one.
I hope this helping someone.

Just to add, most lights have sensors which will need deleting from MQTT explorer too.

After doing all this I still see them in the MQTT integration in HA. I have a feeling I will have to delete this and re-add to finally get rid of them.

Surely this needs to be worked on as it’s not very user friendly!

Like others on here I was struggling with removing an entity/device from the integration MQTT:Mosquitto Broker. I following all the advice at the top but they there still showing here.

So this is what worked for me:

I’m using on a Pi3 and have hassio. I went to config then a folder called ‘.storage’ inside there are some files. You need to open and edit these files. ‘core.entity_registry’ and ‘core.device_registry’ to take our references to the devices you want to delete.

Be careful deleting things in here, you’ll need to delete all the lines that reference your device. So for me it was all these lines in the ‘core.device_registry’ file:

                "area_id": null,
                "config_entries": [
                "connections": [],
                "id": "ba641b5022c04c4dac826c34e260be19",
                "identifiers": [
                "manufacturer": "OSRAM",
                "model": "LIGHTIFY LED CLA60 E27 RGBW (AC03645)",
                "name": "0x7cb03eaa00add667",
                "name_by_user": "Osram2",
                "sw_version": "Zigbee2mqtt 1.9.0",
                "via_device_id": null

You can use any text editor to edit, and do make sure you keep a backup in case anything goes wrong.

I then rebooted my Pi3 from the hass.io/system menu and then the device was gone.

Hope this can help someone.


Hello everyone! Sorry to be a pain, I’m quite new to this world so I still miss the confidence with the tree files and common names in general.
I get how to clean the MQTT database but I struggle to make sense of:

I used Autodiscovery for the set-up so I don’t have the mqtt: setting in my config.yaml.
Where do I find the declaration of this zombie device in my hassio?
Many, many, thanks to whoever can help me!

Here you go:

Configuration in the left menu, afterwards on the right. :slight_smile: :slight_smile: :slight_smile:

Do these steps are the same as doing force remove in zigbee2mqtt assistant?

Hi, I need help, In Developer Tools, I cannot find any MQTT, How do I get there, a screen shot will be very thankful…Thanks

Below is my Developer Tools Screenshot:

It was moved in (i think) 0.113.0. Now it is here :

I got the first 2 steps right, thanks to @francisp assistant.
Now I stucked at step3, when you mean “entity registry”, do you mean going into
a folder ‘.storage’, and edit the files ‘core.entity_registry’ or/and ‘core.device_registry’ ?

Thanks for your advice.

Just click on your device here and delete

I actually trying to remove a door contact sensor, I realise it has 3 entities, “battery”, “linkquality” and “binary_sensor”, I did not success by trying to remove the main device ID:0x000d6ffffe66ff54, so I try out the “battery” entity first. On step 1. the MQTT log shows:

zigbee2mqtt:error 2020-08-07 15:38:50: Cannot remove, device ‘sensor.0x000d6ffffe66ff54_battery’ does not exist
zigbee2mqtt:info 2020-08-07 15:38:50: MQTT publish: topic ‘zigbee2mqtt/bridge/log’, payload ‘{“type”:“device_removed_failed”,“message”:“sensor.0x000d6ffffe66ff54_battery”}’

Actually I have already disconnect the sensor and bind it back to Tuya Zigbee Hub. To remove the ID in HA-Z2M, do I have to connect it back to HA-Z2M first?
Thanks for your quick reply, appreciate.

now trying forceremove as per advice from mqtt: It says success. Let me try the rest and update later, it looks ok…
zigbee2mqtt:info 2020-08-07 15:50:15: Successfully force_removed 0x000d6ffffe66ff54
zigbee2mqtt:info 2020-08-07 15:50:15: MQTT publish: topic ‘zigbee2mqtt/bridge/log’, payload ‘{“type”:“device_force_removed”,“message”:“0x000d6ffffe66ff54”}’


The easiest way to remove a device from zigbee2mqtt is to install zigbee2mqttassistant, and use force remove


Thanks for your tips, I didn’t understand this part at first when someone post this picture. I was just trying the manual method, type in forceremove into MQTT topic, and it work like charm. It can skip all the steps and they are gone forever…This is what I just did, paste the ID of the device, click publish and everything is gone, not even need to reboot…

Now thanks for your advice and guidance. Now I am trying to use the zigbee2mqttassistant to get it automated,
Thanks Zigbee2MQTT Assistant is a “must have” ADDON

1 Like

I learn many things from here, just give back a little…hope it helps someone…
This is the easiest way to remove MQTT devices.

  1. no need to delete any entities
  2. no need to use MQTT explorer.
  3. no need to install addon
  4. no need to restart and reboot any addon.
  5. they will be gone forever.

Lastly, please install Zigbee2MQTT Assistant from the repository, it provides many tools.


Have you try to re-pair any of the removed device? I’m using the force remove feature too. But I have a hard time to repair the device.