Fixing Matter Problems: Common Errors and Their Solutions

Is your Matter device not adding to your system, and you do not know why? This happens more often than you might think, and the cause is usually quick to find. Setup depends on several parts: smartphone, app, home network, device and, for Thread devices, the border router. If one of them fails, the process stops. Here you will find the most common sources of error and an order in which to check them.

The basics of setup are explained in the article Setting up a Matter device: step by step to a finished device. This article is about troubleshooting.

Matter device not adding: the most common causes

Most problems fall into one of five groups. The following overview helps you classify them:

Symptom	Common cause	What you can do
Device is not found	Bluetooth off or no permission	Check Bluetooth and app permissions
Code is not recognized	Code covered, damaged or wrong	Enter the numeric code or realign the camera
Wi-Fi connection fails	5 GHz network, wrong password, guest network	Use the 2.4 GHz network, check the password
Thread device stays offline	Border router not reachable	Check the border router and network
Device is already taken	Still linked to another system	Remove it from the old system or reset it

Step 1: Check your smartphone and app

Before you look at the device, check the basics. Many failures happen right here:

• Bluetooth is switched on. For many devices, the initial setup uses Bluetooth LE. Without Bluetooth, your smartphone cannot find the device.
• The app has all permissions. Make sure it has access to Bluetooth and, depending on the system, to the local network or location. The names of these permissions differ depending on the operating system.
• The app is up to date. Older versions may not handle newer devices properly.
• Your smartphone is nearby. Especially during the first connection, keep the distance small.

Restarting the app and the smartphone surprisingly often fixes a connection that is stuck.

Step 2: Check the setup code

The setup code is the key to setup. If it is not recognized, the cause is often the scan:

• The QR code is dirty, creased or photographed too small. Try better lighting and a little more distance.
• You can enter the numeric code printed next to the QR code. Watch out for confusions such as O and 0 or I and 1.
• The code belongs to a different device. With multipacks, it is worth reading the code directly on the right device.

Keep the code safe, because it gives access to the device. Do not share it publicly.

Step 3: Prepare the Wi-Fi properly

Many errors with Wi-Fi devices come from the network. Check these points:

• The 2.4 GHz band is enabled. Many Matter devices can only use this band. A network that offers only 5 GHz will not be found.
• The password is correct. Check upper and lower case and special characters. Pasting the password from the clipboard can add spaces.
• Guest Wi-Fi is the wrong choice. On some networks, devices are isolated from each other. Then your control system cannot reach them.
• Smartphone and device are on the same network segment. A smartphone connected via another network or a VPN may not reach the device.

If you have changed your network, for example with a new router or a mesh system, test the setup in the same room where the device is located.

Step 4: Check the border router

Thread devices depend on the border router. If it is not reachable, setup gets stuck or the device appears offline afterwards. Check:

• Is the border router switched on and connected to your home network?
• Is it on the right network, meaning the same home network as your smartphone?
• Is it running as an active Thread border router in your control system?
• Is the device within range of another Thread device or of the border router?

I explain the role of the border router in the article Border router and controller. If you use Thread devices in several rooms, the article Thread, Wi-Fi or Ethernet helps you classify the radio technologies.

Step 5: Reset the device

If the device is still linked to another system or the connection is stuck halfway, a reset can help. The method depends on the manufacturer:

• Some devices have a reset button that you hold down for a specific time.
• With plugs or lamps, switching on and off several times can trigger pairing mode.
• Other devices use a reset option in the manufacturer’s app.

Note: a reset removes the device from every system it was set up in. Check beforehand whether you still need it there, or whether you want to plan the setup again afterwards.

Multi-admin and system limits

If you want to add a device to a second system and that fails, the cause is often the limits of the device or the system. Not every device supports multi-admin, and not every combination of systems works equally well. Check the manufacturer’s information to see whether sharing is intended. I explain the process in the article Multi-admin.

If nothing helps

If the problem persists, a systematic approach helps:

1. Note at which step the process stops. The message from the app is valuable here.
2. Set up the device directly next to your control system or the border router.
3. Update the firmware of the device and the software of your system, if updates are available.
4. Reset the device and start the setup again.
5. Contact the manufacturer’s support or the community of your control system.

If you are looking for a new device, the device directory helps you check the radio technology and certification before you buy. That way you avoid many problems from the start.

Conclusion: a systematic approach saves time

If a Matter device will not add, follow a fixed order: first smartphone and app, then the setup code, Wi-Fi, border router and finally the reset. Many causes lie in the preparation rather than in the device itself. With a little patience, most problems can be solved without outside help.

Frequently asked questions

Why is my Matter device not being found?

Usually Bluetooth on the smartphone is switched off or the app has no permission. Also check that you are close to the device and that it is in pairing mode.

My Wi-Fi network is not shown during Matter setup. What should I do?

Many Matter devices only support the 2.4 GHz band. Enable it in your router or use a network that offers this band.

My Thread device stays offline. What is the cause?

Often the border router is not reachable or is not on the same home network. Check the power supply, the network connection and the setting in your control system.

Do I have to reset a device before I set it up again?

Yes, if it is still linked to a system or can no longer connect. The method depends on the manufacturer and is described in the manual.

Can I use a Matter device in two systems at the same time?

That depends on the device and the system. Many devices support multi-admin, but not all of them, and not in every combination. Check the manufacturer’s information.