Troubleshooting Matter Devices with Aqara

Having trouble adding a Matter device, keeping it connected, or using it across smart home platforms? Follow this guide to identify the connection type and work through the relevant checks.

This guide covers Aqara Matter devices, supported Aqara devices connected through an Aqara Matter bridge, and compatible third-party Matter devices added to Aqara Home. Availability depends on your product, region, firmware, and the platform you use.

Find your issue

What you are experiencing	Where to start
Not sure which hub or network you need	1. Check your setup
Device cannot be found, QR code fails, or setup times out	2. Cannot add a Matter device
Need to select a controller during setup	2D. Select a controller during setup
Device works in one platform but cannot be added to another	3. Cannot share a device with another platform
Device is offline, unreachable, or slow to respond	4. Device is offline or responds slowly
Aqara devices are missing from a platform after connecting a hub	5. Devices connected through an Aqara Matter bridge
Features, status updates, or automations do not work as expected	6. Features or automations are missing or not working
Problems started after changing a router, hub, or Wi-Fi settings	7. After a network or hub change
Unsure whether a factory reset is necessary	8. When should I factory-reset a device?
Need to enable and export device diagnostic logs	9. Enable and export device diagnostic logs
Want to configure a supported Aqara Matter device in Aqara Home without an Aqara hub	10. Connect to Aqara Home without an Aqara hub

1. Check your setup

Matter is the smart home connectivity standard. Thread, Wi-Fi, and Ethernet provide the network connections that Matter can use. A Zigbee device does not become a native Matter device simply because it connects to a Matter-enabled hub.

Your setup	What you need
Matter over Thread	A Matter controller supported by your chosen platform, plus a compatible Thread Border Router. One hub may provide both functions.
Matter over Wi-Fi	A supported Wi-Fi network and the Matter controller or setup arrangement required by your chosen platform. A Thread Border Router is not required for this connection.
Matter over Ethernet	A wired LAN connection and the Matter controller or setup arrangement required by your chosen platform. A Thread Border Router is not required for this connection.
Aqara devices exposed through a Matter bridge	A compatible Aqara hub with Matter bridging enabled, supported child devices, and a Matter controller for the receiving platform. The child devices keep their existing connection to the Aqara hub.

Your phone and hub have different roles. During setup, your phone and app usually act as the Matter commissioner: they help add the device to the platform. After setup, the platform's Matter controller handles control. Your phone does not normally need to remain near the device or maintain a Bluetooth connection. The required controller and network infrastructure must remain available.

Check these basics first:

• Confirm Matter support for your exact product model and, where applicable, its selected operating mode. Follow the product instructions before switching protocols or modes.
• Update your phone's operating system, Aqara Home, the other smart home app, and the firmware of the device and relevant hubs.
• Confirm that your chosen platform supports the device type and features you want to use.
• Keep the required controller, bridge, and Thread Border Router powered on and connected.
• For a straightforward setup, connect your phone, controller, and Wi-Fi or Ethernet device to the same home LAN. A Thread device connects through its Thread Border Router, not directly to your Wi-Fi network.

2. Cannot add a Matter device

A. The device cannot be found

1. Check power. Confirm that the device is powered on. For a battery-powered device, remove any battery isolation tab and check the battery installation and charge.
2. Enter pairing mode. Follow the product manual and check the indicator or app confirmation. Pairing windows expire; reopen the window if necessary.
3. Check phone permissions. Enable Bluetooth and allow the permissions requested by the setup app, such as Local Network, Nearby Devices, or camera access. Permission names vary by operating system.
4. Reduce distance during setup. Keep your phone close to the device. For Thread devices, also keep the device within good range of the Thread Border Router or an existing Thread router.
5. Check whether it is already set up. If the device is connected to another Matter platform, use that platform's sharing flow instead of attempting first-time setup again. See Section 3.
6. Retry setup in one app at a time. Fully close and reopen the setup app before retrying. If it still fails, restart the device and the relevant controller, then retry after they are fully available.

B. The QR code or setup code does not work

• Use the Matter setup code, not a HomeKit setup code or an Aqara setup code.
• If scanning fails, use the app's manual code-entry option, if available.
• If the device is already connected to a Matter platform, generate a fresh sharing code in that platform. Do not assume the printed first-time setup code will work for an additional platform.
• If the code is missing or damaged, contact Aqara Support. Do not use a code from another device.

C. Setup starts but fails or times out

For Matter over Wi-Fi:

• Check the Wi-Fi name, password, and the bands and security modes supported by the product. If the device requires 2.4 GHz, make sure that band is available.
• Your phone does not normally need to stay on 2.4 GHz if both Wi-Fi bands belong to the same reachable LAN. If setup has trouble selecting the correct network, temporarily connecting the phone to 2.4 GHz may help.
• Avoid networks that require a browser sign-in, such as hotel or public Wi-Fi.

For Matter over Thread:

• Confirm that a compatible Thread Border Router is online and available to the setup flow. A Matter controller without Thread Border Router functionality is not sufficient on its own.
• Update the relevant hubs and phone, then retry near the Border Router.
• Do not enter a Wi-Fi password for the Thread device unless the product's setup instructions specifically ask for one for another purpose.

For all connection types:

• Avoid guest networks or isolated IoT networks during diagnosis. Client isolation, VLAN rules, or multicast filtering may prevent setup or local control.
• Matter relies on local IPv6 communication. Your home network must allow the required IPv6 traffic and local discovery, including mDNS. An IPv6 internet subscription is not required.
• Temporarily disconnect a phone VPN if it blocks local-network access. Do not disable your router's firewall or expose devices to the internet.
• If using a managed network, ask the administrator to check local discovery and reachability rather than changing advanced settings at random.

If the problem continues, note the exact error and setup stage before considering a factory reset.

D. Select a controller during setup

• Controller missing: Confirm that the supported controller is online and set up in the intended account and home/location in the receiving app. If the app lets you choose a controller, select one that supports your device and setup method.
• Fully close and reopen the app. If needed, restart the device and relevant controller or Border Router one at a time, wait until each is available, and retry.

Do not post Thread network credentials publicly or try to extract them using unsupported tools. Follow current product and platform instructions if a supported setup flow requests network credentials.

3. Cannot share a device with another platform

Matter's multi-admin feature lets a compatible device connect to more than one smart home platform. Sharing access to a home within one platform is different from adding the device to another platform.

1. Open a platform where the device already works.
2. Find its Matter sharing or additional-platform setup option. The name and location vary by app.
3. Open a new pairing window and generate a sharing code.
4. In the receiving platform, start its add-device flow and use that code before it expires.
5. Keep the device, existing platform, and receiving controller online until setup finishes. Keep the sharing screen open if the app instructs you to do so.

If sharing fails:

• Generate one fresh code and complete that attempt before opening another sharing session.
• Confirm that the receiving platform supports the device type and has its required controller.
• Check local-network reachability between the receiving controller and the device or bridge.
• For Thread devices, keep the existing Thread network and Border Router available. Adding another Matter platform does not automatically move the device to a different Thread network.
• If the app reports that the device has reached its platform or connection limit, remove an unused platform connection using a supported management flow. Limits vary by product.
• If the original platform is no longer accessible, check whether another connected platform or the product's own app can open pairing. Contact support before resetting if you need to preserve the existing setup.

To stop sharing with one platform: Use that platform's supported remove-device or connection-management flow, and check its removal warning before confirming. Removing a Matter platform connection is not the same as factory-resetting the device. Other platform connections should remain available when only the selected connection is removed; automations in the removed platform may stop working.

4. Device is offline or responds slowly

First, identify what is affected

Symptom	Check first
Only one device is affected	Its power, battery, placement, connection, and firmware
Several Thread devices are affected	Thread Border Router availability, Thread coverage, and recent power or network changes
All devices behind one bridge are affected	The bridge's power, LAN connection, and connection to the receiving platform
The device works in one platform but not another	The affected platform's controller, local reachability, and software
Local control works but remote control fails	Internet access and the platform's remote-access requirements
Control is reliable but one feature fails	Feature compatibility or software behavior; see Section 6

Before changing the network, fully close and reopen the affected app to rule out a stale status display. If safe and applicable, test the device's physical control to help distinguish an app or connectivity issue from a power or device issue.

Check the power supply

• A battery-powered device can become unreliable before its displayed battery level reaches 0%. If it disconnects repeatedly or behaves intermittently, check the battery and replace it with the specified type when needed, even if the app still reports some charge.
• For plug-in devices and hubs, use a power supply and cable that meet the product's specifications. Check for loose connections or an outlet that is being switched off.
• Repeated restarts or unexpected power loss may indicate unstable power rather than a Matter connection problem. For hardwired products, have installation and supply issues checked by a qualified professional; do not open the device or alter wiring as a troubleshooting step.

For Matter over Thread

• Move the Thread Border Router out of enclosed cabinets and away from metal surfaces or dense groups of electronics.
• Check whether a powered Thread device or Border Router was recently unplugged. A smart bulb switched off at the wall cannot provide a routing path.
• Improve coverage with compatible router-capable Thread devices on the same Thread network, where needed. Battery-powered sensors generally do not extend the mesh, and not every mains-powered Thread device acts as a router.
• A Zigbee repeater or a Wi-Fi extender does not directly extend Thread coverage.
• If practical, test the affected device nearer the Border Router. Improvement suggests a coverage or interference issue, though it does not identify the cause by itself.
• After a restart or topology change, allow the network to recover before making further changes. Restart one component at a time rather than repeatedly restarting everything.

Multiple Thread Border Routers can improve resilience when they serve the same Thread network. Hubs from different ecosystems may use separate Thread networks; adding another hub does not guarantee that they will merge. Do not routinely switch off other Border Routers as a troubleshooting shortcut.

For Matter over Wi-Fi or Ethernet

• Check Wi-Fi coverage or the Ethernet cable and switch connection.
• Check whether the router, access point, or LAN configuration recently changed.
• Confirm that local device-to-device communication is allowed, including between wired and wireless clients.
• Restart the affected device and, if necessary, the relevant controller. Restart the home router only when there is evidence of a wider network issue; this temporarily interrupts other devices.

For battery-powered devices

Battery-powered devices may sleep between events and may not refresh every value continuously. Test an actual supported event, such as opening the contact sensor, rather than relying only on a timestamp. Check battery condition and follow the manual if a wake-up action is needed. A sleeping device should still deliver supported events under normal conditions.

5. Devices connected through an Aqara Matter bridge

When an Aqara hub acts as a Matter bridge, supported child devices are presented to another platform through that hub. They are not individually converted into native Matter devices.

The bridge cannot be added

1. Confirm that the exact hub model and firmware support Matter bridging.
2. Confirm that the hub is online and working in Aqara Home.
3. Follow the hub's Matter connection instructions and use its Matter setup or sharing code, not a child device's code or a HomeKit code.
4. If the bridge is already connected to a Matter platform, use its supported additional-platform pairing flow.
5. Check LAN reachability between the hub and the receiving platform's controller.

The bridge is connected, but a child device is missing

• Check that the child device is online and works in Aqara Home.
• Verify that the hub supports exposing that exact model through Matter. A device working in Aqara Home does not guarantee Matter bridging support.
• Check that the receiving platform supports the bridged device type.
• Update the hub and receiving platform, then allow time for discovery and refresh the app.
• If the issue remains, contact support with the hub and child-device models. Do not reset the bridge or remove working child devices as the first step.

All bridged devices become unavailable

Check the bridge before troubleshooting individual child devices. Loss of bridge power, LAN connectivity, or the receiving controller's connection can affect every device exposed through it. If only one child device is affected, check that device's original connection to the hub, such as its Zigbee connection.

6. Features or automations are missing or not working

Matter support does not mean every feature appears identically in every app. Availability depends on the product's implemented Matter capabilities, whether it is bridged, and the receiving platform's support and user interface.

A feature is available in Aqara Home but missing elsewhere

• Check the product documentation and the receiving platform's supported features for that device type.
• Advanced settings, manufacturer-specific functions, historical data, energy information, or particular automation triggers may not be exposed or displayed in every platform.
• Update the device, bridge, and platform software. An update may resolve a known issue, but it does not guarantee that an unsupported feature will become available.
• Use Aqara Home for supported Aqara-specific settings where required.

If basic commands work reliably but a particular value or command does not, investigate feature support or software behavior before changing network hardware.

Status or automations do not update as expected

1. Trigger a real device event and check whether it appears in the affected app.
2. If the event appears but the automation does not run, check the automation's conditions, schedule, permissions, and enabled state.
3. Confirm that the platform exposes the required event as an automation trigger. A visible value is not always available as a trigger.
4. Check whether the automation requires an online hub, cloud service, or internet connection. Matter connectivity alone does not make every automation local.
5. If the device was removed and added again, repair any automation references to its old entry.

The device appears twice

The same physical device may be connected through Matter and another integration, or through more than one bridge path. Identify which entry belongs to each integration before removing anything. Update affected automations first, and avoid factory-resetting the physical device just to remove a duplicate app entry.

7. After a network or hub change

What changed	What to check
Wi-Fi name or password	Use the product's supported network-update flow. Some products may require setup again; check the manual before resetting.
Router or access point	Confirm LAN reachability, local IPv6, discovery traffic, and client-isolation settings. Keeping the same Wi-Fi name and password does not preserve every network setting.
Thread Border Router	Restore the previous Border Router if available, or follow the platform's supported migration or recovery process. A replacement may create a different Thread network.
Matter controller	Follow the platform's controller replacement instructions. Replacing a controller is not the same as sharing a device to another platform.
Aqara Matter bridge	Follow the hub's supported migration instructions. Child devices and receiving-platform connections may need separate attention; do not assume they transfer automatically.

If the old setup still works, keep it available until the migration is complete.

8. When should I factory-reset a device?

Consider a factory reset only after checking compatibility, pairing mode, permissions, updates, power, and network connectivity — or when the product's recovery instructions or support team recommend it.

Before resetting:

• Save a private copy of the device's setup code.
• Record connected platforms, important settings, and automations.
• Check the manual for the exact reset procedure and its effects. Some products distinguish network reset, Matter connection reset, and full factory reset.
• For a bridge, check how the reset affects child devices and other integrations.

After resetting, add the device to one platform first and confirm that it works. Then share it with additional platforms. Old app entries may need to be removed and automations may need repair.

9. Enable and export device diagnostic logs

Device diagnostic logs can help the support team investigate an issue. This feature is supported only on selected devices; refer to the product manual for availability and activation instructions.

Step 1. Open device diagnostic logs

• Open Aqara Home and go to Profile.
• Tap Help & Feedback at the bottom of the page, then tap Device diagnostic logs.

Step 2. Prepare the device

• Keep Bluetooth enabled on your phone and stay close to the device.
• On supported devices, press the reset button 7 times in succession to activate log diagnostics, then attempt to connect through the app.
• This procedure applies only to devices that support this feature. Check the product manual before proceeding.

Step 3. Select the device

• The app searches for and lists devices that support diagnostics, such as:
  • Hub M3
  • Door and Window Sensor P2
• If multiple devices of the same model appear, tap the find/identify button next to a device to locate the one you want to diagnose.

Step 4. Enable log storage

• Turn on log storage. It is off by default and must be enabled manually.

Step 5. Export the logs

• Tap the export logs button.

Step 6. Complete the export

• During export, do not leave the page or turn off Bluetooth. Keep your phone close to the device.
• After export, choose one of the following options:
  • Share with Aqara: Upload the logs to the Aqara cloud.
  • Save the diagnostic log file manually: Save the exported file locally on your phone without uploading it to the Aqara cloud.

10. Connect to Aqara Home without an Aqara hub

Selected Aqara Matter devices can be added to Aqara Home using a compatible third-party Matter hub, without an additional Aqara hub. First set up the device in the supported third-party Matter ecosystem, then share it with Aqara Home using Matter multi-admin to access supported settings and controls.

This setup is available only on selected Aqara Matter devices. Check the product manual for compatibility and supported settings. It still requires a compatible third-party hub; the device does not connect directly to your phone over Thread.

Before you start

• Update Aqara Home to the latest version.
• Have a supported third-party Matter ecosystem hub already set up in your home. For the setup described here, the hub must provide both Matter controller and Thread Border Router (TBR) functions. See Aqara Everything Matter for the relevant hub list and compatibility information.
• Install the third-party ecosystem's app on your phone. Confirm that the app and hub are working and can add devices normally.
• Connect your phone and the third-party hub to the same home LAN, such as the same router's Wi-Fi and/or Ethernet network. Avoid guest networks or settings that isolate devices from one another.
• Start with an Aqara Matter device that has not been set up or has been factory-reset according to its manual. If it already works in the third-party ecosystem, skip Step 1 and proceed to sharing; do not reset a working device just to add it to Aqara Home.

Step 1. Set up the device in the third-party ecosystem

• Put the Aqara Matter device into pairing mode according to its manual.
• In the third-party app, start the add-device flow and scan the Matter QR code supplied with the device, or enter its Matter setup code if supported.
• Complete setup and confirm that the device appears online and its supported functions work in that app.

Step 2. Generate a Matter sharing code

• Open the device's settings in the third-party app and find the Matter sharing or additional-platform setup option.
• Open a new pairing window and generate a Matter sharing QR code or numeric code.
• Keep the code available and use it before it expires. Do not substitute the device's printed first-time setup code for this sharing code.

Step 3. Add the device to Aqara Home

• Open Aqara Home, start the add-device flow, and scan the sharing QR code generated by the third-party app.
• If the QR code is displayed on the same phone, use manual code entry if available, or display the QR code on another screen so it can be scanned.
• Follow the app's instructions to complete setup, then open the device page to access the settings and controls supported without an Aqara hub.

If setup without an Aqara hub fails

• Confirm that the exact device model supports connecting to Aqara Home without an Aqara hub and that Aqara Home and the device firmware are up to date.
• Check that the device still works in the third-party app and that the hub and Thread network remain online.
• Confirm that the phone and hub can communicate on the local network, and grant the permissions requested by Aqara Home.
• If the sharing code has expired, generate a fresh code in the third-party app and retry in Aqara Home.

Keep the third-party hub and Thread Border Router available after setup. Supported settings and controls depend on the product; connecting without an Aqara hub does not guarantee access to all Aqara hub features, remote access, or every automation capability. Refer to the product manual for the supported scope.

Still need help?

Contact Aqara Support with:

• Product model, firmware version, and whether it uses Thread, Wi-Fi, Ethernet, or a Matter bridge.
• Hub, controller, Thread Border Router, and bridge models, as applicable.
• Phone model, operating system, and relevant app versions.
• The exact error message, setup stage, and approximate time of failure, including your time zone.
• Whether the device works in Aqara Home or another platform.
• Whether one device or multiple devices are affected, and any recent network or hub changes.
• Troubleshooting steps already attempted and diagnostic logs, if requested through an official support channel.