Troubleshooting integration errors

Cloud-to-cloud Matter

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:

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

The process is similar for local integration using the Local Home SDK. Once you master the troubleshooting flow, you can easily go back and forth between metrics and logs to gain insights on your errors.

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 95th Percentile Latency chart is an important indicator for how your smart home Action is performing for your users. Sudden fluctuations in this chart might indicate your systems might be unable to catch up with the requests. Periodically checking this chart is advised to see any unexpected behavior.
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.

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

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:

Debugging Smart Home Codelab: Quick start guide to debug smart home cloud integration.
Debugging Local Home Codelab: Quick start guide to debug smart home local integration.

Cloud Logging