Commissioning Failures

Commissioning is the process of adding a Matter device to your smart home. This guide covers common failures and platform-specific troubleshooting.

QR Code Scanning Failures

Symptoms

• Camera won’t focus on QR code
• “Invalid code” error message
• App doesn’t recognize the QR code

Solutions

1. QR code quality

   • Ensure QR code is clean and undamaged
   • Remove any protective film over the code
   • Try scanning from different angles and distances

2. Lighting conditions

   • Avoid direct sunlight on QR code
   • Ensure adequate ambient lighting
   • Eliminate glare from reflective surfaces

3. Manual code entry

   • Use the numeric manual code printed on device
   • Enter code carefully, checking each digit
   • Format: Typically 11 or 21 digits

4. Camera issues

   • Clean smartphone camera lens
   • Grant camera permission to the app
   • Close other apps using the camera

Timeout During Commissioning

Symptoms

• Process hangs at “Connecting” or “Configuring”
• “Commissioning timeout” error
• Device shows partial setup

Diagnostic Flow

Commissioning Starts
        │
        ▼
   Device Found?
    │       │
   YES      NO → Network Discovery Issue
    │
    ▼
 Pairing Code Accepted?
    │       │
   YES      NO → Invalid/Used Code
    │
    ▼
 Network Credentials Sent?
    │       │
   YES      NO → Network Connectivity Issue
    │
    ▼
 Device Responds?
    │       │
   YES      NO → Device Power/Signal Issue
    │
    ▼
Commissioning Complete

Solutions

1. Before retrying

   • Factory reset the device
   • Power cycle hub and router
   • Clear device from platform (if partially added)

2. During commissioning

   • Keep smartphone within 2 meters of device
   • Don’t navigate away from the app
   • Ensure stable internet connection

3. Network preparation

   • Temporarily disable 5GHz band (use 2.4GHz only)
   • Disable any VPN on smartphone
   • Ensure no firewall blocking port 5540

”Device Already Claimed” Errors

Symptoms

• “Device is already owned by another account”
• “Device already in use”
• Cannot add device to your home

Causes

• Previous commissioning not fully removed
• Device was tested and not reset
• Demo unit returned to inventory

Solutions

1. Factory reset device

   • Perform full factory reset procedure
   • Wait for device to pulse (indicates ready state)
   • Retry commissioning

2. Remove from previous platform

   • If known, remove device from previous owner’s app
   • Factory reset after removal
   • May require previous owner cooperation

3. Contact support

   • Provide device serial number
   • Request device unclaim from cloud
   • Support can release device remotely

Hub Not Responding

Symptoms

• “Hub offline” error
• “Cannot reach hub” message
• Commissioning fails at hub communication step

Platform Hub Requirements

Solutions

1. Hub status check

   • Verify hub has power and network connection
   • Check hub status in platform app
   • Restart hub if showing offline

2. Network connectivity

   • Ensure hub and smartphone on same network
   • Verify hub has internet access
   • Check for hub firmware updates

3. Hub replacement

   • Try commissioning with different hub
   • Some platforms allow multiple hubs
   • Test hub placement relative to device

Platform-Specific Failures

Apple Home Issues

Common problems:

• “Accessory not supported”
• “Home data not available”
• iCloud sync issues

Solutions:

1. Verify Apple ID two-factor authentication enabled
2. Check Home app permissions (Bluetooth, Local Network)
3. Sign out and back into iCloud
4. Reset Home configuration (last resort)
5. Ensure home hub is running latest tvOS/iOS

Requirements:

• iOS 16.2+ / iPadOS 16.2+ / tvOS 16.2+
• iPhone 8 or newer recommended
• iCloud Keychain enabled

Google Home Issues

Common problems:

• “Can’t communicate with device”
• “Something went wrong”
• Device appears but won’t respond

Solutions:

1. Clear Google Home app cache
2. Check Google Account sync status
3. Verify device location settings
4. Ensure Google Home app is updated
5. Revoke and re-grant Matter permissions

Requirements:

• Google Home app 3.0+
• Android 9+ or iOS 15+
• Matter-enabled Google device on network

Alexa Issues

Common problems:

• “Device not responding”
• Discovery fails
• “Unable to add device”

Solutions:

1. Enable “Local Network” permission in Alexa app
2. Update Echo device firmware
3. Disable and re-enable Matter skill
4. Check Amazon account region settings
5. Verify Echo device supports Matter

Requirements:

• Echo device (4th gen+ recommended)
• Alexa app updated
• Amazon account in supported region

SmartThings Issues

Common problems:

• “Device offline”
• Hub connection failures
• Edge driver issues

Solutions:

1. Restart SmartThings hub
2. Check hub LED status (solid green = good)
3. Clear SmartThings app cache
4. Verify hub firmware is current
5. Check for known service outages

Requirements:

• SmartThings Hub v3 or Aeotec hub
• SmartThings app updated
• Samsung account in good standing

Home Assistant Issues

Common problems:

• “Commissioning failed”
• “Unable to add Matter device”
• Integration errors

Solutions:

1. Verify Matter integration installed and configured
2. Check Home Assistant has network access
3. Ensure Matter server is running
4. Review Home Assistant logs for errors
5. Restart Matter integration

Requirements:

• Home Assistant 2023.2+
• Matter integration enabled
• Stable network connection

Factory Reset Procedure

Before re-commissioning, always factory reset the device:

Standard Reset (Power Cycling)

Re-Commissioning Steps

After factory reset, follow this sequence:

1. Prepare network

   • Verify hub is online and responsive
   • Ensure smartphone on correct Wi-Fi network
   • Confirm mDNS is working

2. Clear platform cache

   • Remove any partial device entries
   • Restart platform app
   • Check for orphaned devices

3. Commission device

   • Open platform’s add device screen
   • Scan QR code or enter manual code
   • Follow on-screen prompts
   • Keep smartphone near device throughout

4. Verify operation

   • Test basic controls (on/off, dim)
   • Check device appears correctly
   • Test from multiple control points

5. Document success

   • Note device location
   • Record room assignment
   • Save serial number for support reference