Troubleshooting

Sample app

If you encounter any issues when using the Home APIs, you can collect logs for further debugging. Collecting logs from the mobile device requires Android Debug Bridge (adb). If you need assistance from Google, collect the logs from both the Android devices and the hub and open a ticket in the issue tracker with the relevant information and logs associated with it.

Collect Android logs

Your mobile device must be connected to your local machine for all steps involving adb.

Install adb

If you haven't already, set up Android Debug Bridge on your local machine:

Install "adb" on your computer.
Turn on Developer Options and USB Debugging on your Android phone.

Get mobile device ID

Get the ID of your mobile device:

adb devices

List of devices attached
device-id    device

Store this value in a variable called phoneid:
```
phoneid=device-id
```

Version information

We recommend gathering all version information related to your setup whenever you decide to collect logs. This is required if you need to share issues with Google.

Save various device information to variables:

containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep -m 1 "versionName" || true); ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep -m 1 "versionName" || true); androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true); androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true); chimeradump=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider || true); homemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.home" || true); optionalhomemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.optional_home" || true); threadinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.threadnetwork" || true); enabledfeatures=$(echo "$chimeradump" | grep "Enabled features" | grep -i "home" | sort -u || true)

Save all variables to a file named _versions.txt:

Expand to show commands to save variables to a file

The entire block can be copied and pasted to a terminal at once.

versionfile="_versions.txt"
echo "Saving version info to $versionfile"
echo "Container version: $containerinfo" > $versionfile
echo "Home Module version: $homemoduleinfo" >> $versionfile
echo "Optional Home Module version: $optionalhomemoduleinfo" >> $versionfile
echo "Thread Module version: $threadinfo" >> $versionfile
echo "GHA version: $ghainfo" >> $versionfile
echo "Android version: $androidversion" >> $versionfile
echo "Android API version: $androidapiversion" >> $versionfile
echo "Found enabled features: $enabledfeatures" >> $versionfile

Verify the contents of _versions.txt:

cat _versions.txt

Expand to show sample file output

Container version:     versionName=26.26.34 (190400-945364269)
Home Module version:             com.google.android.gms.home [v262634001]
Optional Home Module version:         com.google.android.gms.optional_home [262634025] ...
Thread Module version:             com.google.android.gms.threadnetwork [v262634001]
GHA version:     versionName=4.22.28.0
Android version: 14
Android API version: 34
Found enabled features:             Enabled features: appsearch_impl, brella_dynamite, dck_management...

This file can now be provided to Google as needed for troubleshooting.

Enable verbose debugging flags

Before collecting Android device logs or running a bug report, configure the logger buffer size and enable verbose debugging tags for Google Home and GMS components:

# Clear existing device logs and expand logger buffer size
adb -s $phoneid logcat -b all -c
adb -s $phoneid logcat -G 8M

# Enable GMS Service ID verbose flags
adb -s $phoneid shell setprop log.tag.gms_svc_id:168 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:304 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:305 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:319 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:336 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:360 VERBOSE

# Enable GHP and Matter log tags
adb -s $phoneid shell setprop log.tag.CameraCommissioningPlugin VERBOSE
adb -s $phoneid shell setprop log.tag.HomeSdk VERBOSE
adb -s $phoneid shell setprop log.tag.HomeClient VERBOSE
adb -s $phoneid shell setprop log.tag.InteractionApiChimeraService VERBOSE
adb -s $phoneid shell setprop log.tag.MatterCommissioner VERBOSE
adb -s $phoneid shell setprop log.tag.SampleApp VERBOSE

Collect Android logs by scripts

To capture live Android device logs during a debugging session:

Follow the instructions in Enable verbose debugging flags to clear existing logs, expand the buffer size, and set verbose logging tags.
Close all applications running on the mobile device.
Clear existing log buffer noise before starting your test:
```
adb -s $phoneid logcat -c
```
Start the log collection process in a terminal window:
```
adb -s $phoneid logcat | tee android-logs_$(date +%Y%m%d%H%M%S).txt
```
Leave this terminal window open. This will capture logs from your device for as long as the process runs.
Run your app and perform all user interface actions needed to reproduce the issue.
Once done, stop the logcat process in the terminal by pressing Ctrl+C (or Cmd+C on Mac).
Logs from this session are saved in android-logs_YYYYMMDDmmss.txt. Attach both android-logs_YYYYMMDDmmss.txt and _versions.txt to any bug reports.

Collect Android logs by adb bugreport

Capture a full Android bug report when you need to share detailed diagnostic information covering system-level issues, crash dumps, or low-level network and Bluetooth debugging:

Matter BLE Commissioning: When reporting a Matter commissioning issue regarding BLE, enable the Bluetooth HCI snoop log in Developer Options (Settings > Developer options > Enable Bluetooth HCI snoop log) before reproducing the issue.
Pre-test Setup: Before running your test, follow the steps in Enable verbose debugging flags to enable the verbose debugging properties on your device.
Capture Bug Report: After running your test and reproducing the issue, run the following command to generate a full bug report archive:
```
adb -s $phoneid bugreport ./android-bugreport_$(date +%Y%m%d%H%M%S).zip
```
Advanced Debugging Information: The generated android-bugreport_YYYYMMDDmmss.zip file contains comprehensive system-level diagnostic data—including full system dumps, memory statistics, battery diagnostics, and low-level subsystem traces—providing more advanced information for debugging.

Cast hub device logs

You can view device logs for your Google Nest hub using this method, which is supported for the following models:

Google Home
Google Nest Audio
Google Nest Hub
Google Nest Mini

To enable a Cast hub for local logs retrieval:

Set up Android Debug Bridge.
Get the IP address of your hub:
- From the hub, if it has a screen:
  1. Swipe down from the top of the screen
  2. Tap the Settings icon
  3. Find the device IP address: On a Nest Hub (2nd gen), go to Device information > Technical information > IP Address
- From GHA on your phone:
  1. Tap the device to bring up the device details page
  2. Tap the Settings icon to bring up the settings page
  3. Find the device IP address: go to Device information > Technical information > IP address
On a computer on the same Wi-Fi network as the device:
```
  adb connect ip-address
  adb logcat
```
To provide logs to someone, perform the operation that is failing and pipe the output to a text file:
```
  adb logcat -d > platform-logs.txt
```

Automations

Edge detection

Automations in the Google Home ecosystem feature edge detection, which is logic that verifies that a starter only activates when there is an actual state change, as opposed to a state update which merely repeats the previous state of the device.

For example, if turning on a light is a starter, edge detection verifies the starter only activates if that light device goes from off to on, as opposed to from on to on (no change).

Automation doesn't behave as expected

After accounting for edge detection, if an automation doesn't behave as expected:

Check each device to make sure that it is functioning properly independent of your automation.
Have a look at the automation graph for your automation, comparing it against your automation DSL, to reveal any potentially incorrect assumptions on your part.
Observe device state in the Google Home app during the execution of your automation.
Check to make sure that all the devices referenced by the automation are present in the structure where you expect them to be. Deleting a device that an automation depends on can have unintended consequences. See Impact of device deletion on automations.

Automation runs when it shouldn't

If your automation runs when it shouldn't, examine the starter criteria. It may be necessary to add additional logic to make sure that a change in state is captured only once and triggers the automation only once.

Automation doesn't compile

Make sure your app contains all the necessary imports, including each class corresponding to the different node types as well as the traits you're referencing.

Automation creation fails validation

If automation creation does not pass validation, a warning or error message provides information about the issue. For more information, refer to the ValidationIssueType reference.

List function throws exceptions

When calling the Automation API List function, read handlers may throw exceptions due to missing API features. To mitigate this, delete the affected automation.

To do this:

Check to make sure adb installed is installed. See Install adb.

Retrieve the ID of the automation from the Android logs by invoking:

adb logcat -s GhpNative

Example logs:

adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse

INTERACTION RESPONSE -> SendCommandsResponse:
1 {
1: "automation@global"
3 {
  1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
  2:
  5 {
    1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
    1 {
        1: "1111-2222-3333-44444-55555" // Automation ID to delete
        2: "structure@2222-3333-4444-5555-6666"
...

If multiple automation IDs need to be deleted, you can use your terminal pager to control the output:

adb logcat -s GhpNative level:debug | less

Delete the automation using the automation's ID:

structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))

Discovery API logs a warning when a trait is unregistered

If the Discovery API logs a warning for Trait not found, this means the API is trying to use the trait for Discovery candidates, but it won't succeed because the trait was not registered during initialization. For example:

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

The trait identifier is home.matter.6006.clusters.fc43, which corresponds to RelativeHumidityControl. To determine the trait name from an ID, see the Trait index.

From this example, RelativeHumidityControl needs to be registered during app initialization. Refer to Registering traits to add your trait to the registry.

OAuth

If you have an existing OAuth client

If you already have a verified OAuth client for a published app, you can use your existing OAuth client to test the Home APIs.

Google Home Developer Console registration is not required to test and use the Home APIs. However, you will still need an approved Developer Console registration to publish your app, even if you have a verified OAuth client from another integration.

The following considerations apply:

There is a 100-user limit when using an existing OAuth client. For information about adding test users, refer to Set up the OAuth consent screen. Independent of OAuth verification, there is a Home APIs-imposed limit of 100 users who can grant permissions to your application. This limitation is lifted upon completion of Developer Console registration.
Developer Console registration should be sent for approval when you are ready to restrict device-type grants through OAuth in preparation for updating your app with the Home APIs.

Important: The Google Home Developer Console is not yet available for registration.

For Google Cloud apps that are still pending OAuth verification, users can't complete the OAuth flow until verification is complete. Attempts to grant permissions will fail with the following error:

Access blocked: <Project Name> has not completed the Google verification process.