Troubleshooting Guide for Smart Home Add-ons

---

Having trouble with your Alexa smart home add-on? If your add-on 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 add-ons 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 add-on 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 add-on 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. Add-on 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 add-on 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 add-on.

Try this

To validate add-on responses

1. Verify the add-on response complies to the interface specification for success and error responses. For details, see the documentation for each interface that you support in your add-on.
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 add-on 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 add-ons

Smart home add-ons 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 add-on 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 add-on 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 add-on.
5. For directives that have missing or expired access tokens, return EXPIRED_AUTHORIZATION_CREDENTIAL. Here, Alexa can guide the customer to relink their Alexa add-on.
6. If your add-on 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.

Related topics

• Alexa.ErrorResponse Interface
• About the Automated Testing Service
• Best practices for state reporting
• Operational metrics

---

---

Last updated: May 13, 2026