Troubleshooting Guide for Smart Home Skills

Having trouble with your Alexa smart home skill? If your skill encounters errors, review the information in this guide for possible resolutions to common issues.

High user-perceived error rate

Operational metrics provide valuable insights into the performance of smart home and video skills. By monitoring user-perceived errors (UPEs), you can identify and address issues that might impact the user experience. Regular analysis of these metrics allows you to tune and debug your skill so that it operates reliably and accurately.

You can find these errors on the Analytics > Capability Directives page on the Alexa developer console. For more details, see View Operational Metrics for Smart Home and Video Skills.

Alexa exceptions

Issue: SKILL_RESPONSE_TIMEOUT_EXCEPTION

Alexa logs the SKILL_RESPONSE_TIMEOUT_EXCEPTION after waiting for a response from your skill for more than eight seconds. This error might occur due to high traffic to your Amazon Web Services (AWS) Lambda function.

Symptoms

Your Lambda function receives too many simultaneous requests due to large spikes in traffic. For example, customer routines executing at specific times, such as 7 AM for morning routines, might cause these spikes.

Try this

To increase configured limits in your Lamba function

  1. Increase the Lambda memory allocation to at least 256 MB and increase the timeout of the Lambda function to at least eight seconds. These increases are free.
  2. Increase the concurrent executions limit in your Lambda function. Skill developers can request an increase in the maximum number of concurrent execution environments. This increase is free. Set the limit high to accommodate peak traffic.

Symptoms

Lambda traffic still exceeds Lambda concurrent execution limits and causes Lambda to throttle (discard) requests to manage the load. For more details, see Understanding Lambda function scaling.

Try this

To increase the concurrent execution limit

  1. If the increased concurrent execution limit is insufficient, request Amazon AWS to increase the burst concurrency limit. Burst concurrency allows Lambda to temporarily scale up to a higher number of execution environments to handle traffic spikes.
  2. Use provisioned concurrency at peak times. Provisioned concurrency allows you to pre-warm and maintain a set of execution environments ready to handle traffic spikes. It also helps to avoid latency caused by cold starts. Provisioned concurrency comes at an additional cost, but when combined with burst concurrency, can mitigate throttling during peak traffic.
  3. To reduce the cost of provisioned concurrency, you can use autoscaling to spin up additional provisioned execution environments before the anticipated traffic spike and scale them down after the spike passes.

Issue: INVALID_SKILL_RESPONSE_EXCEPTION

Alexa logs an INVALID_SKILL_RESPONSE_EXCEPTION when the skill response is malformed or doesn't comply with the JSON response definition.

Symptoms

Large number of INVALID_SKILL_RESPONSE_EXCEPTION errors reported in the metrics for your skill.

Try this

To validate skill responses

  1. Verify the skill response complies to the interface specification for success and error responses. For details, see the documentation for each interface that you support in your skill.
  2. Make sure that the response header is valid includes the messageId and correlationToken properties. The correlation token in the response should match the correlation token in the request.
  3. Make sure the endpoint is correct.
  4. Make sure that there are no missing or extra properties in the response payload.
  5. Test and debug your smart home skill in the Alexa developer console.
  6. For most smart home interfaces, use the Alexa Smart Home Message JSON Schema to validate your response payload.

Error responses from skills

Smart home skills report errors to Alexa by responding to directives with Alexa.ErrorResponse or more specific error responses defined by the interface. For more details about error types and error interfaces, see Error type values.

Issue: ENDPOINT_UNREACHABLE

Report ENDPOINT_UNREACHABLE when the endpoint is unreachable or temporarily offline. For example, the endpoint might be turned off, disconnected from the customer's local area network, or connectivity between the endpoint and bridge or the endpoint and the device cloud might have been lost.

To let Alexa know the health of your device, implement Alexa.EndpointHealth. When your device encounters an issue, report the error reason with Alexa.EndpointHealth so that Alexa can inform the customer of device degradation.

Symptoms

Endpoint is offline or disconnected from the network.

Try this

To let Alexa know the state of your device

  1. Respond to directives with Alexa.ErrorResponse with error type, ENDPOINT_UNREACHABLE.
  2. And, send an Alexa.ChangeReport that includes Alexa.EndpointHealth in the payload with the connectivity property set to UNREACHABLE and the reason property set to the connectivity failure reason. Include the last known state of the reportable properties from other controllers in the context property.

Symptoms

Your device connects to Alexa with a bridge or hub and the bridge or hub is offline.

Try this

To let Alexa know the state of your device

  1. Respond to directives with Alexa.ErrorResponse with error type, BRIDGE_UNREACHABLE.
  2. And, send an Alexa.ChangeReport that includes Alexa.EndpointHealth in the payload with the connectivity property set to UNREACHABLE and the reason property set to the connectivity failure reason. Include the last known state of the reportable properties from other controllers in the context property.

Issue: NO_SUCH_ENDPOINT

Report this error if the specified endpoint no longer exists or has been unreachable for a long period of time.

Symptoms

The device is unreachable for a period of time.

Try this

To reconnect your device

  1. Prompt the user to reconnect the device from your app.
  2. Respond to directives with Alexa.ErrorResponse with error type, NO_SUCH_ENDPOINT.
  3. After the device is reachable, send an Alexa.ChangeReport that includes Alexa.EndpointHealth in the payload with the connectivity property set to OK. Include the current state of the reportable properties from other controllers in the context property.

To remove a device that's no longer in use

  1. Prompt the user to reconnect the device from your app.
  2. Respond to directives with Alexa.ErrorResponse with error type, NO_SUCH_ENDPOINT.
  3. After you determine that the device is no longer in use, send an Alexa.DeleteReport so that Alexa can remove the endpoint from the customer's Amazon account and the Alexa app. Amazon recommends that you remove the device after 365 days of no usage.

Symptoms

Your skill receives directive related to a device that the customer deleted from their account in your system. If you sent a previous Alexa.DeleteReport, it might have failed.

Try this

To remove a device that's no longer in the customer account

  1. Respond to directives with Alexa.ErrorResponse with error type, NO_SUCH_ENDPOINT.
  2. To remove the device from the customer's Amazon account, send an Alexa.DeleteReport so that Alexa can remove the endpoint from the customer account and the Alexa app.

Issue: INTERNAL_ERROR

Report INTERNAL ERROR when an error occurs that isn't described by one of the other error types, such as a runtime exception. However, don't use this error type for most errors. Amazon recommends that you always send a more specific error type, if possible. The more accurate the error type, the better Alexa can guide customers through appropriate steps and a relevant speech response.

To determine more specific error types

  1. If the skill receives unexpected directives that their device doesn’t support, respond with INVALID_DIRECTIVE.
  2. If the endpoint isn't accepting directives due to a hardware failure, report HARDWARE_MALFUNCTION.
  3. If the endpoint needs a firmware update, report FIRMWARE_OUT_OF_DATE.
  4. For directives that have malformed or invalid access tokens, report INVALID_AUTHORIZATION_CREDENTIAL. Here, Alexa can guide the customer to relink their Alexa skill.
  5. For directives that have missing or expired access tokens, return EXPIRED_AUTHORIZATION_CREDENTIAL. Here, Alexa can guide the customer to relink their Alexa skill.
  6. If your skill receives too many requests in a short period of time, return RATE_LIMIT_EXCEEDED.
  7. If you have questions about the error type to report, contact Alexa developer support.
Was this page helpful?

Last updated: frontmatter-missing