Use this checklist with the HiveMQ migration guide. It is a configuration and acceptance guide, not a certification of every Home Assistant deployment. Managed checks on October 20, 2026 failed retained conformance, including expected-value replay and packet-flag checks. Do not accept a retained-dependent migration until your exact Home Assistant workload passes restart and state recovery tests. Retained messages require Growth or Scale; Starter does not include them.
Plan discovery and permissions first
Inventory device discovery topics, state topics, command topics and availability topics. Home Assistant can rediscover entities when devices resend configuration after its birth message, or from retained discovery messages. These are different recovery paths. Check the behavior implemented by each device; a broker change alone does not make devices resend their configuration.
For an isolated demo device, create separate device and Home Assistant identities with the following policies. Extend them only for the real topics you have reviewed:
| Identity | Topic filter | Permission |
|---|---|---|
| Demo device | homeassistant/sensor/migration_demo/temperature/config | Publish |
| Demo device | migration-demo/temperature | Publish |
| Demo device | homeassistant/status | Subscribe |
| Home Assistant | homeassistant/sensor/migration_demo/temperature/config | Subscribe |
| Home Assistant | migration-demo/temperature | Subscribe |
| Home Assistant | homeassistant/status | Publish |
These narrow policies cover only this demo sensor, not every integration. Real device groups need additional discovery, command and availability rules. Test denied operations as well as allowed operations. Do not give every device a blanket # grant.
Reconfigure the broker
Back up Home Assistant and the old connection settings first. In Settings → Devices & services → MQTT → Reconfigure, set the RunMQTT secure hostname, port 8883 and the new Home Assistant device credentials. In the other settings, enable broker certificate validation, using Auto when the certificate is trusted by the bundled roots. Keep hostname verification enabled. Review the protocol version required by your installed Home Assistant release; the current official documentation requires MQTT 5.
Updating Home Assistant does not update the sensors, gateways or backend applications. Each client needs the target hostname and its own credentials. Coordinate the switch so Home Assistant receives states from devices on the same broker. The official MQTT integration documentation is the source for version-specific UI options.
Verify discovery and current state
With Home Assistant connected and the demo policies active, use your authorized test publisher to publish this synthetic JSON to homeassistant/sensor/migration_demo/temperature/config at QoS 1:
{
"name": "Migration demo temperature",
"unique_id": "runmqtt_migration_demo_temperature",
"state_topic": "migration-demo/temperature",
"unit_of_measurement": "°C",
"device_class": "temperature"
}
Then publish 21.5 to migration-demo/temperature. Confirm the demo entity appears with that state. Publish 22.0 and confirm it updates. This proves one active discovery/state path, not offline recovery. Use the retain setting only when deliberately testing the retained recovery path on a supported plan.
Restart Home Assistant. If the device implements birth-triggered discovery, verify that it subscribes to homeassistant/status and resends its configuration and current state after receiving online. For retained discovery/state, verify replay after a fresh subscription and compare with the actual current device state. Test availability and stale-state handling separately. Do not replay transient commands or trigger events as retained state.
Accept or roll back
Require discovery after restart, correct current state, expected offline/online transitions, denied unauthorized actions and successful command acknowledgements for real controllable devices. Repeat after a network interruption and device restart. Include representative subscription counts and startup bursts, not just one demo sensor.
If any required behavior fails, stop expansion and restore the coordinated old connection configuration while HiveMQ remains available. Keep the source until the migration is accepted and finish before retirement. For this demo, remove the discovered entity by publishing an empty discovery payload, clear any retained demo config and state, and revoke test identities. Remove the temporary test entity from Home Assistant if needed.
See sessions and delivery for the retained compatibility caveat. Contact RunMQTT with versions, required features and a sanitized failure sequence if you need an assessment; do not send access secrets or household data.