Commissioning and multi-fabric
Treat "scanning the code" as building a trust relationship, not a one-off join. You will learn to handle pairing data safely, add controllers one at a time, and judge the real impact before you remove, reset or clean up orphaned data.
A successful commissioning is not the same as long-term reliability
Matter Hub is a Matter bridge: it turns Home Assistant entities into one bridge and the endpoints under it, so a Matter controller such as Apple Home, Google Home or Alexa can onboard it into its own home. It is not a second controller that replaces the one you already have. Commissioning, the step that onboards the bridge, makes the controller and the bridge establish trust they can keep verifying; once the pairing screen closes, the fabric, the secure operating session and the subscription all still exist.
At home the usual problem is not "nothing shows up at all". It is that the first ecosystem works, the second one fails to join, or one ecosystem shows offline after a restart. If you treat every problem with a reset, you can cut off a fabric that was working, lose room and automation links, and still leave orphaned devices on the controller side. The goal of this chapter is to make you identify the layer first, and then make the smallest possible change.
A mental model from bridge to state reporting
| Layer | What it means | How it usually fails | Safe check |
|---|---|---|---|
| Bridge / endpoint | The bridge is the Matter node that gets commissioned, and Home Assistant entities map to the endpoints under it. | Every device disappears, or the types are wrong. | Check the bridge run state, the Devices mappings and the filter preview first. |
| Commissioning window | Lets a new controller establish trust for a limited time. Matter Hub provides the first one; after that, a controller already in the fabric opens pairing mode. | The app cannot find the accessory, or the pairing data is rejected. | Work out first whether this is initial onboarding or an extra fabric; do not reset first. |
| Fabric | One administrative domain and its certificate relationships. The same bridge can belong to several fabrics. | One ecosystem goes offline while the others stay fine. | Compare the status of each controller in the bridge details or in Health. |
| Session | A recoverable secure communication session between a controller and the bridge. | Control times out for a while and may come back later. | Watch whether the session is rebuilt and whether the network is reachable. |
| Subscription | The controller subscribes to attribute or event changes so that state is pushed to it. | Control works, but the app state lags or sticks at an old value. | Compare the HA state with what the controller shows, and check the subscription instead of re-commissioning. |
A fabric is not "a user account inside one home", and a session is not a fabric. Several family members sharing an Apple home are usually still one Apple fabric; adding Google Home is what makes a second fabric. The rooms, names, household members and automations inside a controller app belong to that controller, and multi-fabric does not copy them to another ecosystem.
Where the safety line runs for QR and manual pairing data
A QR code and manual pairing data are the sensitive entry point that lets a new controller into the commissioning flow. Use them only between the local Matter Hub admin screen and the official controller app you are working in; do not paste them into chat, tickets, public screenshots, log attachments or a repository. Redact them completely in tutorial screenshots too, rather than covering only a few of the characters.
- The first QR code: scan the Matter Hub screen directly with the first controller's official app wherever you can, and do not download it, forward it or photograph it for later; the same QR code cannot be used to join a second fabric.
- Manual entry afterwards: find the bridge you already onboarded in the first controller, open "pairing mode" to get the data for that one attempt, then type it into the second controller's numeric-code entry point; this guide gives no example values.
- Where to run it: avoid screen sharing, recording or onlookers; keep pairing mode open only as long as the addition needs, and do not keep the data afterwards.
- Troubleshooting notes: record only the time, the bridge name, the controller type, the stage and the redacted error, never the pairing data or internal identifiers.
Keep release channel, maturity and controller support separate
| Fact | Conclusion for Stable 2.0.55 | Do not infer |
|---|---|---|
| Release channel | This chapter is based on the Stable code at tag v2.0.55 with a pinned commit, plus the pinned add-on. | That the Alpha channel, the Testing channel or a later version behaves the same way. |
| Product maturity | Bridge commissioning, fabric health information and the orphan cleanup workflow all exist in Stable; the ordinary bridge flow is described as a mature feature. | That every device type inside Stable is equally mature. |
| Experimental features | Server Mode with several entities does appear in Stable, but it is still "an experimental feature inside Stable". | That you can promise production support for it, or that it is exactly the same as a bridge. |
| Controller support | Whether a bridge, a given device type or a cluster is accepted is still decided by the controller and its version. | That a successful onboarding guarantees every endpoint, attribute and event is shown. |
So an established fabric only proves that the trust relationship is in place; a session only proves that a communication session exists right now; a subscription comes closer to proving continuous reporting. In the end you still have to test "display, control and state reporting" yourself on every representative type.
A safe multi-fabric join procedure
Pin down the bridge identity and contents first
Open Bridges in Matter Hub, confirm that the target bridge is running and that its name is recognizable, and cross-check the endpoints you expect to expose in Devices or in the filter preview. Do not change the name, the port, the filter or the mapping while you are commissioning.
Back up and record the current working baseline
Back up the persisted data the way your deployment requires; record only the bridge name, which controllers are already attached, the rough device count and the test results. Never write pairing data or internal identifiers into those notes.
Add the primary controller first
Open the commissioning window in the bridge's pairing area, then in the primary controller app choose to add a Matter accessory and scan the local QR code; use the manual entry point only when you cannot scan. When it finishes, confirm that the bridge and a few representative endpoints are visible.
Verify state in both directions
Toggle one low-risk light or switch from the controller and confirm that the Home Assistant state updates; then operate it from Home Assistant and confirm that the controller not only controls it but also receives the state change.
Open pairing mode from the primary controller
In the first controller's home settings or bridge details, find the bridge you already onboarded and choose to open pairing mode. It produces the one-time manual data the next controller needs; do not rescan Matter Hub's first QR code, and do not save or forward the data.
Enter that one-time data in the next controller
Add one new fabric at a time. In the second app's Add Matter device flow, choose the numeric-code / manual entry point and type in exactly what the first controller is showing at that moment. As soon as it finishes, test display, control and state reporting.
Tidy up rooms and names in each ecosystem
Sort out rooms and display names separately inside each ecosystem. Do not expect the first controller's rooms, automations or household members to sync to the second.
Close the change window and watch
Once every addition is done, stop changing the bridge structure, and watch each fabric's session and subscription through a restart and a stretch of ordinary use. Keep the successful baseline so you can compare against it later.
Remove, reset and orphan cleanup are three different things
| Action | When it applies | Main impact | When not to do it |
|---|---|---|---|
| Remove the accessory from the controller | You are sure you only want to leave that ecosystem and keep the other fabrics. | That controller's room, name and automation links may stop working. | When it is only a brief No Response and the session can recover. |
| Remove the fabric | You have confirmed an administrative relationship is no longer used, and you can identify the right one. | That fabric can no longer control the bridge; the other fabrics are independent in theory, but you still have to verify it. | When you cannot tell which fabric it is, when you have no backup, or when household members still depend on it. |
| Reset Bridge | The persisted trust data cannot be recovered, you plan a full rebuild, and you accept re-commissioning every controller. | It may cut off every fabric and leave stale accessories on the controller side that you have to remove separately. | When one endpoint misbehaves, one controller is offline, or a name or room is wrong. |
| Orphan cleanup | The dry run shows leftover entity identity / mapping data for entities already deleted from HA whose tombstone has passed at least the seven-day protection period. | It only clears leftover entity identity and mapping data, not fabrics; a wrong deletion can still cost a reappearing entity its original mapping identity. | When the HA registry has not fully loaded, the deployment disk is not mounted, a restore is unfinished, or you do not understand the candidate list. |
Orphan cleanup clears the identity / mapping data left behind by entities that were permanently deleted from the HA registry. It does not clear Matter fabrics, and it is not a general connectivity fix. v2.0.55 previews with a dry run first and uses a seven-day tombstone to reduce false calls caused by an entity vanishing briefly. If HA has not fully loaded or the persistence disk is not mounted correctly, restore the normal deployment and data paths first, and only then assess the candidates.
Keep the blast radius inside one fabric
A small home can join two controllers with a single lean bridge. Once you have more devices, a mix of types, or controllers whose capabilities clearly differ, splitting the bridge is usually easier to maintain than resetting often. Split on blast radius, controller support and area, not by exposing the same entity again and again at random.
- Start with a "core bridge": put only the representative types every controller renders reliably on it, such as lights and switches.
- Give special types their own bridge: verify covers, vacuums, advanced sensors and experimental types in small batches first.
- Give every bridge a recognizable, stable name, and do not keep changing the structure after onboarding.
- Test one bridge, one fabric and one type per change, so your troubleshooting evidence points somewhere.
Do not reset a bridge the first controller is already using happily just because the second controller does not support some type. Reduce what the second controller sees with a filter or a split first, and keep the fabric that already works.
Find a safe fallback point from the symptom
The app cannot find the bridge at all
Confirm that the bridge is running and that the commissioning window is still valid, and make sure the phone and the network Matter Hub sits on can do local IPv6 and mDNS discovery. Fix the network interface, the VLAN or the multicast path first; do not reset.
It says commissioned, but the endpoints are incomplete
Cross-check the filter, the Devices mappings and the device types the controller supports. A successful fabric does not mean the controller accepts every type; use a plain light or switch as your reference.
Only one controller shows offline
If the other fabrics are fine, the bridge and HA are not necessarily at fault. Look at that fabric's session and subscription, that controller's home hub and the network path, and avoid removing every fabric.
Control works but the state does not update
Compare the real Home Assistant state with the controller app and check whether the subscription is still alive; reopen the app first and watch the session recover, and do not let re-commissioning stand in for subscription troubleshooting.
A grayed-out old accessory is still there after removal
That is usually a room entry or a cached item on the controller side. Remove the stale accessory in the original controller first; do not wipe all of Matter Hub's storage over it.
Orphan cleanup lists items you are not sure about
Cancel the operation, and confirm that the HA registry has fully loaded, that the persisted data is mounted and that any restore has finished. Reassess only when you can prove the entity was deleted from HA and the candidate identity / mapping has passed the protection period.
FAQ
Does multi-fabric sync rooms, names and automations?
Can the second controller just scan the first QR code?
One fabric is offline. Do I have to reset the whole bridge?
When is it safe to use orphan cleanup?
Can I handle Server Mode in Stable 2.0.55 with the same steps?
Pinned-version and specification sources
- v2.0.55 frontend workflows (including orphan cleanup and the bridge interface)
- The v2.0.55 orphan cleanup implementation
- v2.0.55 bridge data and feature flags
- Pinned Stable add-on configuration
- v2.0.55: Connect multiple assistants to one bridge
- Matter Handbook: Fabric
- Matter Handbook: Commissioning
The sources are pinned to the v2.0.55 commit; what a controller actually shows still has to be verified against each ecosystem's current official support and the version you are running.