Troubleshooting

Stay organized with collections Save and categorize content based on your preferences.

Google Cloud Platform (GCP) provides you the tools to monitor your project reliability via monitoring metrics and debug issues via error logs. Whenever a failure happens when fulfilling user intents, Google Home Analytics pipeline will record that failure on your metrics, and publish an error log in your project logs.

There are two steps to troubleshooting your errors:

  • Monitor the state of your project with smart home metrics.
  • Investigate the issue by checking the detailed error description in the error log.

The process is similar for local integration as well. 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 access your project metrics in the Dashboards section of Google Cloud Console, by following Operations > Monitoring > Dashboards. We have created pre-defined dashboards for each smart home integration type, which are available to your smart home projects out of the box.

You can select Google Home Analytics dashboard to see the aggregated metrics across all your integrations, or select the dashboard for the specific integration type to see detailed breakdowns. There are three charts that are especially useful for monitoring quality and debugging:

The Success Percentage chart is the first chart to start from when you are monitoring your project reliability. Drops in this chart can indicate an outage for 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 chart is most useful when it comes to troubleshoot issues on your smart home integration. 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 Google Home platform and how to troubleshoot them in the chart 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_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.
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 his 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 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.
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.

Searching Logs

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

You can access your project logs in the Logs Explorer section of Google Cloud Console, by following Operations > Logging > Logs Explorer.

There are multiple systems within Google Cloud Platform 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 or custom entries.

To specify a Time Range, click on the time range selection button (where it says "LAST 1 HOUR" in the image above) 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 on the query field, select the resource dropdown, and then choose Google Assistant Action Project. This will add a filter in your query to show logs that originate from your Smart Home project.

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 type of queries including comparators (<, >=, !=) and boolean operators (AND, OR, NOT).

For example, the custom entry below would return errors that come from your smart home project, which 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. For more information on Logs, see Monitoring and logging.

Testing Fixes

Once you identify errors on your smart home integration and issue updates to fix them, we recommend testing your fixes throughly with 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: