Change Zigbee2MQTT base_topic Without Breaking HA

The Zigbee2MQTT docs cover base_topic in one line: an optional MQTT namespace, default zigbee2mqtt. What no page covers is what changing base_topic does to an instance that already has devices paired, entities discovered in Home Assistant, and automations built on both.

The short version is that it isn’t a cosmetic rename. Every Home Assistant entity Zigbee2MQTT created is keyed to the old topic, and none of them follow it across. Here’s the mechanism, what the cleanup actually costs, and the one change you shouldn’t make while fixing it.

What base_topic actually controls

base_topic sets the MQTT namespace Zigbee2MQTT publishes everything under. Change it from the default zigbee2mqtt to, say, zigbee2mqtt_iot, and every state, command, and availability topic moves with it. It has nothing to do with individual device names. That’s the friendly_name layer, a separate setting entirely.

A second, related key lives under the Home Assistant integration config: homeassistant.discovery_topic, default homeassistant. This is the namespace Zigbee2MQTT publishes the discovery payloads under, the messages that tell Home Assistant which entities to create. The docs say it should be different from base_topic to prevent errors in Home Assistant software, which undersells it. Current Zigbee2MQTT versions validate the pair at startup and refuse to run when they match: issue #24761 is a user watching Zigbee2MQTT restart every eight seconds with 'homeassistant.discovery_topic' cannot not be equal to the 'mqtt.base_topic' in the log, typo included. On defaults the two never collide, so if Zigbee2MQTT is running at all, this isn’t your problem.

The full topic tree that lives under base_topic — attribute output, get/set commands, availability — is worth its own read if you haven’t seen it mapped out.

Why you’d actually change it

A few reasons come up, and none of them are about the default being wrong:

• You’re running more than one Zigbee2MQTT instance on the same broker or the same Home Assistant install, and each needs its own namespace.
• You want your MQTT tree to follow a personal naming convention rather than the tool’s default.
• You inherited a config where base_topic was set to something that collides with another namespace on a shared broker, homeassistant itself being the case Zigbee2MQTT now refuses to start on.

What actually breaks: every entity’s unique_id

Home Assistant doesn’t identify an MQTT entity by its topic. It identifies it by the unique_id in the discovery payload, and Zigbee2MQTT builds that string out of three parts: the device’s IEEE address, the entity type, and the base topic. On a default install, a light arrives as 0x00178801012362c4_light_zigbee2mqtt.

Change base_topic and that last component changes with it. Every discovery payload now carries a unique_id Home Assistant has never seen, so it does the only thing it can and registers a second, separate entity. The originals stay in the entity registry, still pointed at topics nothing publishes to any more, and go unavailable for good. Issue #23294 reports that outcome end to end: a base topic that moved from zigbee2mqtt to zigbee2mqttHA, and every Zigbee entity rediscovered with a _2 suffix.

That’s a different failure class from entities going unavailable after a bridge restart, which is a bridge/state availability problem rather than a registry one.

Recovering, and the one change to avoid

The recovery on record comes from a Home Assistant Community thread opened in September 2024 and marked solved that November: reconfigure the MQTT integration in Home Assistant. That works, and it’s worth knowing why. Removing and re-adding the MQTT config entry drops the devices and entities it owns, which is what finally clears the stranded half. The reporter put it at roughly 95% of entities recovered, with the remainder needing a manual find-and-replace of the old topic string in automations.yaml.

Order matters if you care about entity_ids. Old registrations that are still present are exactly what forces the _2 suffixes onto the new ones, so clearing them is the step that gets you clean names rather than a permanent set of duplicates.

mqtt:
  base_topic: zigbee2mqtt_iot
  server: mqtt://192.168.10.20:1883

homeassistant:
  enabled: true
  discovery_topic: homeassistant

enabled: true is in there deliberately. Zigbee2MQTT 2.x turned homeassistant into a config section whose enabled field defaults to false, so an edit that sets topics but never sets enabled switches discovery off completely, which looks a lot like discovery not reaching Home Assistant for any other reason.

Cleaning up what the reconfigure doesn’t fix

Automations that reference the old topic string directly, rather than through the entity ID Home Assistant assigned, won’t self-heal when the entities come back.

// before
trigger:
  - platform: mqtt
    topic: zigbee2mqtt/kitchen_motion

// after
trigger:
  - platform: mqtt
    topic: zigbee2mqtt_iot/kitchen_motion

This is a namespace-level rename, not a device-level one, and the difference is bigger than it looks. Renaming an individual device’s friendly_name leaves Home Assistant’s entity IDs alone unless you ask for them to change, because a friendly_name never enters the unique_id. A base topic does, which is why one rename is survivable and the other rebuilds your registry.

Running more than one Zigbee2MQTT instance

If the reason you’re touching base_topic is a second or third instance, there’s a separate upstream limitation to plan around. Issue #22559 documents that bridge-level entities stay hardcoded to the zigbee2mqtt prefix instead of following your configured base_topic. Two instances therefore land as binary_sensor.zigbee2mqtt_bridge_connection_state and binary_sensor.zigbee2mqtt_bridge_connection_state_2, rather than taking names from the topics you set.

Honestly, I think leaving connection_state on the shared prefix is a defensible call: unpicking every hardcoded bridge topic for a minority use case is a lot of churn for an entity almost nobody builds automations against directly.

What to decide before you rename

Pick your topic scheme once, ideally before you pair a single device:

• Give every instance a distinct base_topic from the start if you’re running more than one.
• Leave discovery_topic at homeassistant unless you have a specific reason to move it and are ready to change Home Assistant’s discovery prefix to match.
• If you’re renaming an established instance anyway, budget for clearing the old MQTT entities in Home Assistant and a manual pass through automations.yaml. The rename itself is the quick part.

What this covers, and what it doesn’t

This is a documented-config-behavior explainer, not a device test. It’s built from Zigbee2MQTT’s MQTT and Home Assistant configuration pages, its discovery payload format, two Zigbee2MQTT tracker issues, and one resolved Home Assistant Community thread. No hardware was flashed or paired to write it. What stays local is all of it: base_topic and discovery_topic only change how your own MQTT broker organizes topics, and none of it touches a vendor cloud service.

On the state of those sources as retrieved in September 2026: #22559 is closed as not planned, and #23294 and #24761 are cited for the behaviour they report rather than as open bugs awaiting a fix. The community thread’s recovery is one person’s sequence rather than an official procedure, but the mechanism underneath it is the part that generalizes.

Frequently asked questions

What is the default MQTT base_topic in Zigbee2MQTT?
zigbee2mqtt. It’s set under the mqtt section of the config and can be changed to any string that’s a valid MQTT topic segment.

Can Zigbee2MQTT’s discovery_topic and base_topic be the same value?
No. Current versions check this at startup and refuse to run, logging that homeassistant.discovery_topic cannot be equal to mqtt.base_topic. On defaults they’re already different, zigbee2mqtt and homeassistant, so this only bites when one of them has been set by hand.

Why did my Home Assistant entities go unavailable after changing base_topic?
Because the base topic is part of every entity’s unique_id in the discovery payload. Changing it makes Home Assistant register a fresh set of entities and strands the old set, which stay in the registry pointed at topics that no longer receive anything. Clearing the old MQTT entities is what fixes it, not republishing discovery.

Do I need a unique base_topic for each Zigbee2MQTT instance if I run more than one?
Yes, for the state and command topics. Be aware that bridge-level entities such as connection_state don’t follow a custom base topic even when it’s set correctly, a known limitation closed as not planned upstream.

Will changing base_topic break my existing Home Assistant automations?
Yes, in two ways. Automations referencing the raw MQTT topic string break the moment the topic moves. Automations built on entity_id break too, because the replacement entities arrive with _2 suffixes while the old entity_ids stay held by the unavailable originals.

The rename takes a second. The registry cleanup and the automation pass are the real cost, and they scale with how long the instance has been running. Settle the scheme before the first device pairs and you never pay it.