Matter Hub is not a second controller. It is what the controller is about to trust

Matter Hub is a Matter bridge: it turns Home Assistant entities into one bridge and the endpoints underneath it, so a Matter controller — Apple Home, Google Home or Amazon Alexa — can onboard it into its own home. It does not replace the controller you already run, and it does not hand your Home Assistant areas, automations or Dashboard to that controller wholesale. Home Assistant stays the source of truth for the underlying entities; Matter Hub only handles the mapping and the protocol translation.

Commissioning is the step that onboards the bridge into a controller's home. It is easy to read the pairing screen closing as "done", but what actually happens is that the controller and the bridge establish a trust relationship they will keep re-verifying for as long as the pairing lasts. The fabric, the secure session and the subscription do not stop existing once the screen closes — they are the ongoing relationship, not a receipt for a completed transaction.

The goal across this part is to get you identifying which layer actually failed, then making the smallest change that fixes it — instead of resetting your way to a guess.

A mental model from bridge to state reporting

Five things have to be true, in this order, for a controller to reliably show and control a device through Matter Hub. Each one is a distinct thing that can fail on its own, and none of them proves the one after it is also working.

flowchart TD
  A["Bridge / endpoint — is Matter Hub running, with the right entities mapped?"] --> B["Commissioning window — can a new controller discover it right now?"]
  B --> C["Fabric — has trust already been established with this controller?"]
  C --> D["Session — is there a live secure connection between them right now?"]
  D --> E["Subscription — is state actually being pushed to that controller?"]

A fabric is not "a user account inside one home," and a session is not a fabric. Several family members sharing one Apple home are usually still a single Apple fabric; it is adding Google Home or Amazon Alexa that creates a second, independent fabric. The rooms, display names, household members and automations inside any one controller's app belong to that controller alone — multi-fabric shares the bridge's device capabilities and state, not that household data model, and none of it copies itself across to another ecosystem.

The checklist first, then the safety line around the code itself

What has to be true before you open a commissioning window

Where the safety line runs around the code itself

A QR code and a manual pairing code are the sensitive entry point that lets a new controller into the commissioning flow. Treat them as exactly that: use one only between the local Matter Hub admin screen and the official controller app you are actively pairing with. Never paste one into chat, a support ticket, a public screenshot, a log attachment or a repository — and redact it fully in any screenshot you keep for your own notes, rather than covering only part of it.

• The first QR code: scan the Matter Hub screen directly with the first controller's official app wherever you can. Do not download it, forward it, or photograph it for later — and it cannot be reused to join a second fabric anyway.
• Manual entry afterward: find the bridge you already onboarded inside the first controller, open its pairing mode to get one-time data, and type that into the second controller's numeric-code entry point. This guide does not show an example value, and neither does the source it is built from — a pairing code is never something worth typing out even as a placeholder.
• Where you do it: avoid screen sharing, screen recording, or onlookers. Keep pairing mode open only for as long as the addition actually takes, and do not retain the data afterward.
• What your troubleshooting notes should hold: the time, the bridge name, the controller type, the stage it failed at, and a redacted error — never the pairing data itself, and never an internal identifier.

flowchart TD
  A["Adding a controller to this bridge"] --> B{"Is any controller already joined to it?"}
  B -->|"no — this is the first one"| C["Scan the QR code on the Matter Hub pairing screen directly"]
  B -->|"yes — this is an additional fabric"| D["Open pairing mode from the controller that is already joined"]
  D --> E["Type the one-time manual code into the new controller's entry point"]
  C --> F["Fabric established for that controller"]
  E --> F

Keep the release channel, the maturity, and the controller's own support separate

So an established fabric only proves the trust relationship exists. A session only proves a communication channel exists right now. A subscription comes closest to proving continuous reporting is happening. None of the three is a substitute for actually testing display, control and state reporting yourself, on every representative device type.

Reading Apple-specific support without over- or under-claiming it

Apple's own list of supported Matter categories gives you a ceiling for the ecosystem, but what actually shows up in the Home app also depends on the Apple platform version, the home hub's version, the device type and clusters the bridge declares, and how well that particular endpoint is mapped. "The Matter specification defines it" is not the same claim as "the Home app has a complete UI for it."

• Lights, plugs and switches: a good first baseline. Still verify on/off, brightness, color temperature and color separately — a card appearing is not the same as every attribute working.
• Covers, locks and thermostats: these carry position, direction, safety or mode semantics. Verify a small number first, and do not stop at whether the card merely appears.
• Sensors: you may see the value in the accessory details and still get no card on the home screen, no notification, and no way to trigger an automation from it.
• Vacuums and newer types: support and UI are sensitive to the Apple system version in use. If the Matter Hub side is a partial Matter 1.4 mapping, label the result experimental in your own notes as well.
• Camera and Security plugins: these are experimental plugins inside the Stable channel. Do not claim full support just because Apple Home happens to have a similar accessory category.

A safe multi-fabric join procedure, controller by controller

These eight steps apply whichever controller you are adding — Apple Home, Google Home or Amazon Alexa. The next section walks the Apple-specific screens for step 3 in more detail; the sequence itself does not change by ecosystem.

1. Step 1

   Pin down the bridge's identity and contents first

   Open Bridges in Matter Hub, confirm the target bridge is running and its name is one you recognize, 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.

2. Step 2

   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 your test results — never pairing data or internal identifiers.

3. Step 3

   Add the primary controller first

   Open the commissioning window in the bridge's pairing area, then in the primary controller's app choose to add a Matter accessory and scan the local QR code — use manual entry only when the camera genuinely cannot read it. When it finishes, confirm the bridge and a few representative endpoints are visible.

4. Step 4

   Verify state in both directions

   Toggle one low-risk light or switch from the controller and confirm the Home Assistant state updates. Then operate the same device from Home Assistant and confirm the controller both reflects the control and receives the state change back.

5. Step 5

   Open pairing mode from the primary controller

   In the first controller's home settings or bridge details, find the bridge you already onboarded and 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 what it produces.

6. Step 6

   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 or 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 again.

7. Step 7

   Tidy up rooms and names in each ecosystem

   Sort rooms and display names out separately inside each ecosystem. Do not expect the first controller's rooms, automations, or household members to sync across to the second.

8. Step 8

   Close the change window and watch

   Once every addition is done, stop changing the bridge's structure, and watch each fabric's session and subscription through a restart and a stretch of ordinary use. Keep this working baseline so you have something to compare against later.

sequenceDiagram
  participant K as Controller
  participant M as Matter Hub
  K->>M: scan the QR code, open the commissioning window
  M->>K: exchange certificates, create the fabric
  K->>M: establish a secure session
  M->>K: begin the subscription to attribute and event changes

The Apple-specific screens behind step 3, and what to do right after

This walks the same territory as step 3 above, but with the actual Home app screens named. Onboard a small number of devices and let them settle first — do not bridge every entity you own on day one.

1. Step 1

   Prepare a minimal bridge

   Open the target bridge on the Matter Hub Bridges page and confirm it is running. Use Devices to cross-check that it holds only the entities you expect. Keep one low-risk light or switch as your verification target, and hold off on adding special device types for now.

2. Step 2

   Open the commissioning window

   The bridge's pairing area shows the QR code for this session. Do not download it, screenshot it, forward it, or put it in a support ticket. Only reach for the Home app's manual entry option if the camera genuinely cannot scan it.

3. Step 3

   Add the accessory from the Home app

   On the iPhone, open Home, choose Add Accessory, and scan the QR code on the local Matter Hub screen. If you see an Uncertified Accessory notice or a security prompt, confirm first that you are connecting to your own bridge in the right home — do not tap past it without reading it.

4. Step 4

   Choose the home and wait for onboarding to finish

   Follow the Home app's screens to pick the target home and room, keep the app in the foreground, and keep the phone's network connection steady. Do not restart Matter Hub, the home hub, or the router while this is running.

5. Step 5

   Do the basic naming first

   Give the bridge and its representative accessories names that are short, easy to say aloud, and not duplicated. Avoid a room name identical to an accessory name, and do not rename every endpoint one by one at this stage.

6. Step 6

   Verify both directions

   Toggle the test light from the Home app and confirm the state changes in Home Assistant. Then toggle it from Home Assistant and confirm the card updates in the Home app. Wait for the state report rather than tapping repeatedly to force it.

7. Step 7

   Verify again after a restart

   Restart Matter Hub during a normal maintenance window and confirm the same accessory comes back — not a second copy of it. If duplicates keep appearing, stop making further changes and check the bridge identity and the persisted data instead.

The order for tidying names, rooms and Siri phrases

After onboarding, tidy up room by room inside the Home app. An Apple display name is controller-side data — it does not have to match the Home Assistant entity_id, and editing entity_id to polish the voice experience is the wrong tool. Settle the Home Assistant entities and the Matter Hub mappings first, then adjust display names on the Apple side, which keeps structural changes to the bridge itself to a minimum.

After a rename, test once in the Home app and once with Siri. If Siri gets it wrong, resolve homophones, duplicate names, or room conflicts first — do not reset the bridge over a naming problem. In a multi-fabric setup, none of these Apple-side names sync to Google Home or Amazon Alexa.

Four actions that are easy to reach for by mistake, and four different blast radii

Orphan cleanup clears the identity and mapping data left behind by entities permanently deleted from the HA registry. It does not clear Matter fabrics, and it is not a general connectivity fix. Stable 2.0.55 previews it with a dry run first, and uses a seven-day tombstone to reduce false positives 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 — only then assess the candidates.

flowchart TD
  A["Something about one controller or one device looks wrong"] --> B{"What have you actually confirmed?"}
  B -->|"only want to leave one ecosystem"| C["Remove the accessory in that controller only"]
  B -->|"one whole fabric confirmed unused"| D["Remove that fabric"]
  B -->|"trust data unrecoverable, full rebuild accepted"| E["Reset Bridge — every fabric is affected"]
  B -->|"entities deleted from HA, past the seven-day tombstone"| F["Run orphan cleanup — dry run first"]

Keep the blast radius inside one fabric as you grow

A small home can join two controllers to a single, lean bridge without issue. Once you have more devices, a mix of device types, or controllers whose capabilities clearly differ, splitting the bridge is usually easier to maintain than resetting often. Split by blast radius, by controller support, and by area — not by exposing the same entity again and again at random.

• Start with a "core bridge": put on it only the representative types every controller renders reliably — lights and switches are the usual choice.
• Give special types their own bridge: verify covers, vacuums, advanced sensors and experimental types in small batches, separately.
• Give every bridge a recognizable, stable name, and stop restructuring it once it is onboarded.
• Change one bridge, one fabric, and one type per test, so your troubleshooting evidence always points somewhere specific.

Do not reset a bridge a first controller is already using happily just because a second controller does not support some device type. Reduce what the second controller sees with a filter or a split first, and keep the fabric that already works.

Attack No Response by scope and timing, not by resetting

When the controller's devices and Matter Hub sit on separate VLANs, being able to reach the internet does not mean Matter is reachable on the local network. Matter needs an IPv6 path and local service discovery — do not substitute a public network address, port forwarding, or pasting the QR code onto a remote machine. Once the network path is fixed, let the session recover on its own before you even consider removing the accessory.

flowchart TD
  A["A controller shows No Response"] --> B{"What is the scope of the problem?"}
  B -->|"the whole bridge"| C["Check the Matter Hub process, the network, IPv6 / mDNS, and the bridge identity"]
  B -->|"only one endpoint"| D["Cross-check that entity's state in Home Assistant and in Matter Hub Devices"]
  B -->|"only fails away from home"| E["Check the home hub itself — leave the fabric alone"]
  B -->|"control works, card stuck on an old value"| F["Compare state both ways and wait for the subscription to recover"]
  B -->|"clears itself soon after a restart"| G["Watch it settle and read the startup log — do not restart again"]

Common pitfalls, general multi-fabric

Common pitfalls, Apple Home specifically

The questions that come up every time

Pinned-version and official sources

• v2.0.55 frontend workflows (including orphan cleanup and the bridge interface)
• Matter Hub v2.0.55 exact-commit packages
• 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
• Apple: Pair and manage your Matter accessories
• Apple: Set up your HomePod, HomePod mini, or Apple TV as a home hub

These sources are pinned to the v2.0.55 commit. What a controller actually shows on your screen still has to be verified against that ecosystem's current official support and the version you are running.

Where to go from here