Troubleshooting Matter integration errors

refresh_date: 2023-01-06

Google Cloud provides you the tools to monitor the reliability of your projects with Google Cloud Monitoring and debug issues with Google Cloud Logging error logs. Whenever a failure happens when fulfilling user intents, Google Home Analytics pipeline records that failure on your metrics, and publishes an error log in your project logs.

There are two steps to troubleshooting your errors:

  1. Monitor the state of your projects with smart home metrics.
  2. Investigate issues by checking the detailed error descriptions in the error logs.

Monitoring errors

You can use Google Cloud Monitoring dashboards to access your project metrics. There are some key charts that are especially useful for monitoring quality and debugging:

  • The Success Rate chart is the first chart to start from when you are monitoring the reliability of your projects. Drops in this chart can indicate an outage for a portion or all of your user base. We recommend closely monitoring this chart for any irregularities after each change or update to your project.
  • The Error Breakdown charts are most useful when it comes to troubleshooting issues on your integrations. For every error highlighted in your success percentage chart, an error code is displayed in your error breakdown. You can see the errors flagged by the Google Home platform and how to troubleshoot them in the table below.

Platform Error Codes

Here are some common error codes that you may see in your project logs to identify issues caught by the Google Home platform. Please refer to the following table for troubleshooting information.

Error Code Description
BACKEND_FAILURE_URL_ERROR Google has received an HTTP 4xx error code other than 401 from your service.

Use the requestId in GCP Logging to check your smart home service logs.
BACKEND_FAILURE_URL_TIMEOUT Google's request timed out when trying to reach your service.

Verify that your service is online, accepting connections, and is not over capacity. Additionally, verify that the target device is powered on, online, and synced.
BACKEND_FAILURE_URL_UNREACHABLE Google has received an HTTP 5xx error code from your service.

Use the requestId in GCP Logging to check your smart home service logs.
DEVICE_NOT_FOUND The device does not exist on the partner service side.

This normally indicates a failure in data synchronization or a race condition.
GAL_BAD_3P_RESPONSE Google cannot parse the response from your account linking service due to invalid format or values in the payload.

Use the requestId in GCP Logging to check error logs in your account linking service.
GAL_INTERNAL A Google internal error occurred when Google tried to retrieve an access token.

If you see an increased rate of this error in GCP Logging, contact us for more information.
GAL_INVALID_ARGUMENT A Google internal error occurred when Google tried to retrieve an access token.

If you see an increased rate of this error in GCP Logging, contact us for more information.
GAL_NOT_FOUND The user's access tokens and refresh tokens stored in Google are invalidated and cannot be refreshed anymore. The user needs to relink their account to continue using your service.

If you see an increased rate of this error in GCP Logging, contact us for more information.
GAL_PERMISSION_DENIED A Google internal error occurred when token sharing is not authorized.

If you see an increased rate of this error in GCP Logging, contact us for more information.
GAL_REFRESH_IN_PROGRESS The user's access token is expired and another concurrent attempt to refresh it is already underway.

This is not an issue and no action is needed.
INVALID_AUTH_TOKEN Google has received an HTTP 401 error code from your service.

The access token is not expired but your service has invalidated it. Use the requestId in GCP Logging to check your smart home service logs.
INVALID_JSON JSON response cannot be parsed, or understood.

Check the structure of your JSON response for invalid syntax, such as mismatching brackets, missing commas, invalid characters.
OPEN_AUTH_FAILURE User's access token is expired and Google is unable to refresh it, or Google has received an HTTP 401 error code from your service.

If you see an increased rate of this code, check if you also see an increased rate of errors related to smart home intents or refresh token requests.
PARTNER_RESPONSE_INVALID_ERROR_CODE Response indicates an unrecognized error code.

If your request response indicates an error, make sure to use one provided from our supported error codes.
PARTNER_RESPONSE_INVALID_PAYLOAD Response payload field cannot be parsed as a JSON Object.

Check if the payload field in your request response has matching brackets and is correctly structured as a JSON field.
PARTNER_RESPONSE_INVALID_STATUS Response does not indicate a status, or indicates an incorrect one.

Responses to intent fulfillment requests should indicate a status with either SUCCESS, OFFLINE, ERROR, EXCEPTIONS. You can find more information on handling errors and exceptions.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES One or more intents present in the request is missing on the response.

Verify that your execution response is correctly structured and that the results for all intents from the request are present in your response.
PARTNER_RESPONSE_MISSING_DEVICE One or more devices present in the request is missing on the response.

Verify that your execution response is correctly structured and that all device ids from the request are present in your response.
PARTNER_RESPONSE_MISSING_PAYLOAD Response does not contain a payload field.

Make sure to include a payload field in your request response. You can learn more on how to correctly build an execution response.
PARTNER_RESPONSE_NOT_OBJECT Response cannot be parsed as a JSON Object.

Check all fields in your request response for unintended characters, mismatching brackets or formatting errors. Some unicode characters might be unsupported. Also make sure your response is correctly structured as a JSON object.
PROTOCOL_ERROR Failure in processing the request.

Use the requestId in Google Cloud Logging to check your smart home service logs.
RESPONSE_TIMEOUT Request has timed out while waiting for the response.

The time out period for sending a response is 9 seconds from when the request is sent. Make sure to send a response within this period of time.
RESPONSE_UNAVAILABLE No response is received, or the response does not indicate status.

Responses to intent fulfillment requests should be structured according to the smart home docs and indicate status.
TRANSIENT_ERROR A transient error is an error that will resolve itself.

Most typically these errors manifest as a connection to a device or service being dropped. Also if new connections to a server can't be opened.

Search Logs

Once you get comfortable monitoring your integrations using metrics, the next step is to troubleshoot specific errors using Cloud Logging. An error log is a JSON-like entry with fields containing useful information like time, error code and details regarding the originating smart home intent.

There are multiple systems within Google Cloud that send logs to your project at all times. You need to write queries to filter your logs and find the ones you need. Queries can be based on a Time Range, Resource, log Severity or custom entries.

Query Cloud Logs

You can use the query buttons to help you build your custom filters.

Build Cloud Log Queries

To specify a Time Range, click the time range selection button and choose one of the provided options. This will filter the logs and show the ones that originate in the selected time range.

To specify a Resource, click the Resource dropdown, then choose Google Assistant Action Project. This adds a filter in your query to show logs that originate from your project.

Use the Severity button to filter by Emergency, Info, Debug, and other severity log levels.

You can also use the Query field in the Logs Explorer to enter custom entries. The query engine used by this field supports both basic queries like string matching, and more advanced types of queries including comparators (<, >=, !=) and boolean operators (AND, OR, NOT).

For example, the custom entry below would return errors that originate from a LIGHT device type:

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

Visit the Query Library to find more examples for querying logs effectively.

Testing Fixes

Once you identify errors and apply updates to fix them, we recommend testing your fixes thoroughly with Google Home Test Suite. We provide a user guide on how to use Test Suite, which walks you through testing your changes effectively.

Learning Resources

This document provides the steps to troubleshoot errors in your Smart Home Action. You can also check our codelabs to learn more on debugging:

Previous
Cloud Logging for Matter