Matter and Thread in Home Assistant

Matter lets compatible devices work across ecosystems. Thread is one of the networks a Matter device can use. This guide takes you from choosing hardware to a verified Home Assistant installation, including Matter Server app 9 migration, multi-admin sharing and systematic troubleshooting.

In one minute

Matter is the application standard. Thread and Wi-Fi carry the traffic. Bluetooth is normally used only during commissioning, when the device joins.

Choose the right system first

Need	Strong starting point
New device carrying the Matter logo	Matter over Thread or Wi-Fi
Battery sensors and buttons	Often Zigbee or Matter over Thread
Broad choice of mature low-cost sensors	Zigbee
Long range and specialised devices	Z-Wave
Existing Hue, IKEA or Aqara hub	Keep its native integration or use its supported Matter bridge

Matter is not automatically better than a mature local integration. Choose the path that provides stable local control, the capabilities you need and a realistic recovery path.

Understand Matter, Thread and border routers

• Matter over Wi-Fi uses your regular IP network.
• Matter over Thread uses a low-power IPv6 mesh.
• A Thread Border Router connects that mesh to the LAN.
• A Matter controller commissions and controls devices. Home Assistant is a controller when its Matter integration and Matter Server are running.
• A fabric is a controller’s secure Matter domain. Multi-admin allows a device to join more than one fabric.

A product can use Thread without supporting Matter. Check the Matter mark, its transport and the specific supported device type before buying it.

Prerequisites

You need:

• a current supported Home Assistant installation;
• the Matter integration and Matter Server app on Home Assistant OS;
• IPv6 and mDNS/multicast between Home Assistant, phone, border router and device;
• a current Android or iOS Companion app for commissioning;
• Bluetooth and local-network permissions on the phone;
• a Thread Border Router for Matter over Thread.

Home Assistant Container and other installation types may require a separately hosted Matter Server. Follow the official support matrix; do not assume an arbitrary container network forwards IPv6 and mDNS correctly.

Migrate safely to Matter Server 9 and matter.js

Matter Server app 9 replaces the previous Python/C++ server with matter.js. The documented migration runs automatically on first start. It supports Matter 1.5.1, while the updated OTBR app supports Thread 1.4. This does not promise that Home Assistant supports every device class described by those standards.

1. Create a full Home Assistant backup

   Wait for the job to finish, verify that you can access its encryption key, and download an off-system copy.

2. Record your baseline

   Open Settings → Devices & services → Matter. Record device count, unavailable devices and existing errors.

3. Update Home Assistant, Matter Server and OTBR

   Read the release notes. Avoid restarting several network components at once.

4. Allow the first migration to finish

   First start can take longer. Do not interrupt the app while data migrates.

5. Validate before doing more work

   Confirm the integration loads, the expected devices exist, and at least one command and one state update work.

If migration fails, preserve the Matter Server log, stop adding devices and use the documented restore path. Do not factory-reset devices first; that can remove the only working fabric access.

Add a new Matter device

1. Put the phone on the same local network as Home Assistant.
2. Enable Bluetooth and local-network permissions.
3. Open Settings → Devices & services → Add integration → Matter.
4. Scan the QR code or enter the setup code.
5. Keep the phone close during Bluetooth commissioning.
6. Wait while network credentials and fabric certificates are exchanged.
7. Name the device, assign its area, and test command and state paths.

Store the QR and setup code securely. It is not an ordinary account password, but it can start commissioning while the device is in the appropriate mode.

Share an existing Apple, Google or Amazon device

Use the existing controller’s share function to generate a new temporary Matter code. The original code printed on the device is not always the right code for multi-admin sharing.

1. Start sharing in the platform that already controls the device.
2. Choose Add Matter device in Home Assistant.
3. Enter the new code before it expires.
4. Confirm both controllers can still control the device.

Each controller owns a separate fabric. Removing Home Assistant’s fabric need not remove other controllers, while a factory reset usually removes all of them.

Bridges, multi-admin and safe removal

A Matter bridge exposes devices from another system through Matter. It can be convenient, but may provide fewer capabilities than the vendor’s native Home Assistant integration.

Before removal:

• decide whether you are removing one fabric or resetting the whole device;
• confirm which platform will retain administrative access;
• save logs and device diagnostics;
• remove only the integration or fabric you intend to remove.

Use network visualization

Matter Server 9 can visualize Thread and Wi-Fi relationships. Thread nodes may appear as leader, router or sleepy end device. Link colour and signal data can locate weak paths, but one snapshot is not proof of long-term stability.

Use it to inspect:

• whether a Thread device has a route to a border router;
• whether multiple hops and weak links match a physical placement issue;
• which access point a Wi-Fi Matter device uses;
• whether an incident affects one node or the whole mesh.

Change one variable at a time, allow the mesh to settle, and compare again.

Troubleshooting

The device is not found during commissioning

• Confirm it is reset or in pairing mode.
• Check Bluetooth and Companion app permissions.
• Bring phone and device closer.
• Temporarily disable a phone VPN if it changes local routing.
• Confirm the setup code belongs to this device.

Commissioning stops after Bluetooth

This often points to the network layer: IPv6, mDNS, wrong Wi-Fi credentials, Thread credentials or a border router that cannot reach Home Assistant. Test one boundary at a time rather than repeatedly resetting the device.

A Thread device is frequently unavailable

• Inspect its route and signal in Matter Server.
• Confirm relevant border routers advertise the intended Thread network.
• Avoid metal enclosures and electrically noisy locations.
• Update device, Matter Server and OTBR one component at a time.

It works in Apple or Google but not Home Assistant

Confirm the device was shared into Home Assistant’s fabric rather than merely linked through a cloud account. Generate a fresh share code from the existing controller and repeat the multi-admin flow.

A certificate or unknown device is rejected

Matter Server 9 checks certificate status. Do not apply a generic insecure bypass. Confirm vendor certification, firmware and documentation; development hardware belongs in a deliberate test environment.

When Zigbee or Z-Wave is still the better fit

Do not choose Matter only for the logo. Zigbee offers many inexpensive battery sensors and mature Zigbee2MQTT/ZHA tooling. Z-Wave remains strong for certified specialised devices and sub-GHz range. Matter is most valuable when local IP-based interoperability and multi-admin across ecosystems matter to you.

Zigbee2MQTT

Continue with Zigbee2MQTT setup.

Z-Wave

Continue with Z-Wave in Home Assistant.

Official sources

• Matter integration for Home Assistant
• The Matter upgrade you’ve been waiting for
• Thread integration for Home Assistant
• OpenThread Border Router