Debug Your Smart Home Skill
As you build your smart home skill, you have the following options for debugging it:
- State reporting test tool – This tool enables you to view the properties of the smart home devices associated with your skill, and whether your skill is queried for these properties or it proactively reports them to Alexa.
- Smart home live debugger – This feature enables you to see the
ChangeReport
events that Alexa receives for the smart home devices associated with your skill, including processing errors.
These tools enable you to see information about the smart home devices associated with your skill in the Amazon account that you use to sign in to the Alexa Skills Kit developer console. These tools don't show information from other Amazon accounts.
For more information about building a smart home skill with state reporting, see the following topics:
- Steps to Build a Smart Home Skill
- Understand State Reporting for a Smart Home Skill
- Send Events to the Event Gateway
- Overview
- Prerequisites
- How to use the state reporting test tool
- How to use the smart home live debugger
Overview
Your smart home skill should notify Alexa when a property of your smart device changes. Your skill notifies Alexa by sending a ChangeReport
event to the Alexa event gateway. For more information, see Send Events to the Event Gateway. Sometimes Alexa sends ReportState
directives to your skill, in which case your skill should respond with a StateReport
.
The state reporting test tool and the smart home live debugger help you understand what Alexa knows about the state of your smart home devices, and why. Specifically, these tools can help you understand the following information:
State reporting test tool
- The current state of the smart device's properties.
- Whether Alexa received the state in the response to a
ReportState
directive.
Smart home live debugger
- The
ChangeReport
events that Alexa receives. - Processing errors (if any) for the received
ChangeReport
events. - Whether the state of the smart device's properties were sent in the
payload
or thecontext
of theChangeReport
.
You can use these tools together to see a more complete picture of how your skill interacts with Alexa.
Prerequisites
To use the tools, testing tips, and troubleshooting ideas in this topic, you must have a smart home skill that sends state update (ChangeReport
) events to the Alexa event gateway when the properties of your smart device change. This means that your discovery response (Discover.Response
) indicates "proactivelyReported": true
for all capabilities supported by the smart device. If your skill supports proactive reporting for only a subset of the smart device's properties, then you cannot use the tools described in this topic.
How to use the state reporting test tool
The state reporting test tool enables you to see when your skill is queried for the current state of your smart device's properties, or when Alexa relies on the proactive ChangeReport
events that your skill sends. The following sections explain how to use it.
Step 1: Get access to the tool
To request access to the state reporting test tool, complete the following steps:
- On the Amazon developer portal, sign in with the developer account that is associated with the smart home skill you want to test.
- Open the Customer Details page and note your customer ID. You need your customer ID, not your vendor ID.
-
Open the Developer Support contact page. Use the contact form to send the following information. Replace customer ID with your customer ID from the previous step.
Subject: Alexa
Message: Requesting access to the state reporting test tool for the following customer ID: customer ID
You will be contacted when you are granted access to the tool, or if we need more information.
Step 2: Sign in and enable your skill
The state reporting test tool is an add-on to the existing web-based Alexa app. Make sure to use the Alexa app for your region and sign in with the same developer account that you used to request access to the tool.
The following is a list of regions and the corresponding URL for the web-based Alexa app:
- United States: alexa.amazon.com
- United Kingdom: alexa.amazon.co.uk
- Germany: alexa.amazon.de
- Japan: alexa.amazon.co.jp
- Canada: alexa.amazon.ca
- Australia: alexa.amazon.com.au
- India: alexa.amazon.in
If you haven't already done so, enable and account-link your smart home skill. For more information about how to do this, see Steps to Build a Smart Home Skill.
Step 3: View and understand the state information
In the Alexa app, navigate to Smart Home and then Devices. If the tool is enabled for your developer account, you see extended debugging information for each device. The following image shows an example device:

Each Capability states line in the tool represents a smart device capability (property) that you marked as proactively reported in your discovery response. It also shows the current state for each property, and whether Alexa queried your skill to determine that state.
For example, in the preceding image the Wireless In-wall Dimmer device has the following property states:
- connectivity: OK
- brightness: 0
- powerState: OFF
The following image explains each part of the capability states line.

Pay special attention to the DeepQuery
value. This is a boolean that indicates whether your proactive state update (ChangeReport
) events and other event data are being used, or Alexa queried to obtain the value.
-
DeepQuery: False
: Indicates that Alexa used your proactive state update (ChangeReport
) events to determine this property's value. -
DeepQuery: True
: Indicates that Alexa sent aReportState
directive to the skill. The property's value was received in theStateReport
event sent by the skill in response.
Step 4: Troubleshoot
If you believe you have properly implemented proactive state updates (ChangeReport
events), but the tool shows DeepQuery: True
, check the following:
- If you are working with a newly discovered device, Alexa's state cache might be empty. Try refreshing the Alexa app in your browser. If your device's properties are not sent in the response to a
ReportState
directive (if"retrievable": false
), you need to send aChangeReport
to populate the cache. - Make sure you indicate
"proactivelyReported": true
for all of your device's properties, and that you report all property values. This includes the connectivity property of theEndpointHealth
interface. - Make sure you only report the values of properties that are defined and reportable for your device. For example, if your device implements the
BrightnessController
interface, do not reportbrightnessDelta
asproactivelyReported
because this is not a reportable property. - For thermostat devices, you might need to toggle between HEAT/COOL and AUTO modes to make sure that Alexa has cached data for all the supported set points that were reported during device discovery.
Step 5: Perform additional tests
After you confirm that all of your device's properties show DeepQuery: False
, you should test all of the scenarios for your device that trigger proactive state updates. For each scenario, make sure that the expected property values are shown in the state reporting test tool.
ReportState
directives to your skill.The following are examples of some scenarios that you might want to test.
-
Change your device state without using Alexa. For example, use another application or the physical device controls to turn a device on or off or change its settings. This should cause your skill to send one or more proactive state updates to the Alexa event gateway. In your browser, refresh the Alexa app to confirm that
DeepQuery: False
and that the device's properties show the expected state. -
Test
EndpointHealth
proactive state updates. To do this, remove the power or power source from your device and wait for the device's health polling or heartbeat interval to pass. When your skill reports that the connectivity value has changed, refresh your browser and check the Alexa app for the device state. Then restore power to the device and make sure that all properties are correctly updated in the Alexa app.Note: There is a known issue with the tool that occurs when you are testingEndpointHealth
and the skill response is an error. When the tool receives anErrorResponse
, it displays Failed to retrieve state with no additional information. Until this issue is resolved, you should validate this scenario by checking your logs to make sure you are sending the appropriate JSON response and error codes. -
Make sure that you are sending proactive state updates for all Amazon accounts that have enabled and account-linked the skill, not just the first or more recent accounts. Commonly, customers in the same household share smart home devices but have their own Amazon accounts associated with the skills for those devices.
The state reporting test tool enables you to see information about the smart home devices associated with your skill only in the Amazon account that you use to sign in to the Alexa Skills Kit developer console. The tool doesn't show information from other Amazon accounts. To test this scenario, enable and account-link the skill from different Amazon accounts using the same device credentials. Then change the state of the device without using Alexa. Sign in with each Amazon account, then use the state reporting test tool to confirm that the property states are accurate and that
DeepQuery: False
. This helps confirm that your skill is correctly sendingChangeReport
events for each Amazon account.To test this scenario, you must have at least two Amazon accounts that are enabled to use the tool. Refer to Step 1 if you need to enable additional accounts. Make sure to log in from the account you want to enable before you send the contact form.
Note: If you receive a403 Forbidden
response when you send events to the Alexa event gateway, this indicates that the user has disabled your skill and you can stop sending messages for that user. -
Inspect your log responses to make sure that your proactive state updates are sent correctly to the Alexa event gateway.
If you encounter problems with the state reporting test tool, use the Developer Support contact form to let us know.
How to use the smart home live debugger
The smart home live debugger enables you to see the ChangeReport
events associated with your smart home devices.
Step 1: Access the tool
To view the ChangeReport
events for your smart home devices, complete the following steps.
-
Open the Alexa Skills Kit developer console.
-
Open the smart home skill associated with your smart home device.
-
Open the Test page.
-
At the top of the page, make sure that Device Log and Alexa Smart Home (Beta) are selected.
-
In the Smart Home (Beta) section of the page, make sure the Smart Home live debugger is enabled toggle is on.
When Alexa receives a ChangeReport
event for a smart home device associated with your smart home skill, the event information is added to the device log. For example, see the following image.

ChangeReport
events that you see in the device log are not persistent. When you close your browser tab, the events disappear from the device log. If you open the tool in more than one browser tab, the ChangeReport
events appear only in the most recent active browser tab.For help understanding ChangeReport
events in the device log, see the following sections.
If you encounter problems with the smart home live debugger, use the Developer Support contact form to let us know.
Step 2: Understand ChangeReport events
After you complete the steps in the preceding section, the device log shows the ChangeReport
events that Alexa receives for the smart home devices associated with your smart home skill in the Amazon account that you use to sign in to the Alexa Skills Kit developer console. You don't see ChangeReport
events for devices in other Amazon accounts. Each event in the device log contains a JSON document with details about the ChangeReport
that Alexa received.
When your skill sends a ChangeReport
event to the Alexa event gateway, you receive an HTTP response from the gateway. For the full list of possible HTTP response codes, see Success and Errors in the Send Events to the Event Gateway topic.
Even when your skill receives a 202 Accepted
response from the gateway, there might be errors with the ChangeReport
that prevent Alexa from processing it correctly. You can see these processing errors (if any) in the device log. For a complete list of potential errors, see the following section.
ChangeReport processing errors
The following table lists the processing errors that you might see in the smart home live debugger and the reason why. For more information about the ChangeReport
event schema, see ChangeReport
.
Error Code | Reason |
---|---|
BEARER_TOKEN_NULL_OR_EMPTY |
The bearer token is missing or empty. |
CAUSE_NULL |
The cause object in the payload is missing. |
CAUSE_TYPE_NULL_OR_EMPTY |
The cause object is missing a cause type, or the type is empty. |
CLIENT_ID_NOT_AVAILABLE |
The client ID (customer ID) is missing. |
CONTEXT_NULL |
The context object is missing. |
CONTEXT_PROPERTIES_EMPTY |
The properties object in the context is empty. |
CONTEXT_PROPERTIES_NULL |
The properties object in the context is missing. |
CONTEXT_PROPERTY_NULL |
A property in the properties object in the context is missing. |
DIRECTED_USER_ID_NULL_OR_EMPTY |
The directed user ID is missing or empty. |
DUPLICATE_CONTEXT_PROPERTY |
The context contains two identical properties. |
DUPLICATE_PAYLOAD_PROPERTY |
The payload contains two identical properties. |
DUPLICATE_PROPERTY_MISMATCHED_VALUE |
A single property is reported twice, each with different values. |
ENDPOINT_ID_BLANK |
The endpoint ID is empty. |
ENDPOINT_ID_NULL |
The endpoint ID is missing. |
ENDPOINT_SCOPE_NULL |
The endpoint scope is missing. |
EVENT_ENDPOINT_NULL |
The event endpoint is missing. |
EVENT_HEADER_NULL |
The event header is missing. |
EVENT_NULL |
The event object is missing. |
EVENT_PAYLOAD_NULL |
The event payload is missing. |
HEADER_NAME_NULL |
The header name in the event object is null. |
HEADER_NAMESPACE_NULL |
The header namespace in the event object is null. |
HEADER_PAYLOAD_VERSION_NULL |
The payload version in the header in the event object is null. |
INVALID_ASYNC_EVENT |
The asynchronous response is missing a correlation token. |
INVALID_CHANGE_REPORT |
The ChangeReport contains a correlation token. A ChangeReport must not contain a correlation token. |
INVALID_HEADER_NAMESPACE |
The header namespace must contain the value Alexa . |
INVALID_PAYLOAD |
The payload could not be processed. |
INVALID_PAYLOAD_VERSION |
The payload could not be processed. |
INVALID_PROPERTY |
A property is invalid. |
MISSING_TIME_OF_SAMPLE |
The timeOfSample field in the properties object is missing. |
MISSING_UNCERTAINTY_IN_MILLIS |
The uncertaintyInMilliseconds field in the properties object is missing. |
NEGATIVE_TIME_OF_SAMPLE_DIFFERENCE |
The timeOfSample field contains a time that is after the ChangeReport was received. |
NEGATIVE_UNCERTAINTY_IN_MILLIS |
The uncertaintyInMilliseconds field contains a negative number. This number must be positive. |
PAYLOAD_PROPERTIES_EMPTY |
The properties object in the payload is empty. |
PAYLOAD_PROPERTIES_NULL |
The properties object in the payload is missing. |
PAYLOAD_PROPERTY_NULL |
A property in the properties object in the payload is missing. |
REQUEST_NULL |
The body of the request is missing. |
SCOPE_INVALID |
The endpoint scope is invalid. |
TIME_OF_SAMPLE_LARGER_THAN_THRESHOLD |
The timeOfSample field contains a time that is more than three seconds after the ChangeReport was received. |
UNCERTAINTY_IN_MILLIS_LARGER_THAN_THRESHOLD |
The uncertaintyInMilliseconds field contains a number larger than 14,400,000. |
UNKNOWN_PAYLOAD_VERSION |
The payload version is unsupported. |
USER_IDENTIFIER_NULL_OR_EMPTY |
The user ID is missing or empty. |
Example ChangeReport events in the smart home live debugger
The following are examples of ChangeReport
events that you might see in the live debugger.
Example ChangeReport event (success)
{
"header": {
"customerId": "A1E2P2455A5NYT",
"skillId": "amzn1.ask.skill.awer45bc-f5f7-6f9b-5f24-c3d5f6821d4f",
"skillStage": "development",
"eventType": "SmartHomeChangeReportSuccess",
"messageId": "89bb25e2-9f6c-42b8-8982-ff1dc038c58c",
"applianceId": "ALL"
},
"payload": {
"request": {
"context": {
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-07-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 60000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-07-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
},
"event": {
"header": {
"messageId": "abc-123-def-456",
"namespace": "Alexa",
"name": "ChangeReport",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint-001",
"cookie": {
"path": "/path/for/this/endpoint"
}
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 85,
"timeOfSample": "2017-07-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
}
}
}
}
Example ChangeReport event (processing error)
{
"header": {
"customerId": "A1E2P2455A5NYT",
"skillId": "amzn1.ask.skill.awer45bc-f5f7-6f9b-5f24-c3d5f6821d4f",
"skillStage": "development",
"eventType": "SmartHomeChangeReportFailure",
"messageId": "89bb25e2-9f6c-42b8-8982-ff1dc038c58c",
"applianceId": "ALL"
},
"payload": {
"errors": [
{
"code": "Duplicate_Payload_Property",
"message": "duplicate property in the payload for brightness property"
}
],
"proactiveStateRequest": {
"context": {
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-07-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 60000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-07-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
},
"event": {
"header": {
"messageId": "abc-123-def-456",
"namespace": "Alexa",
"name": "ChangeReport",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint-001",
"cookie": {
"path": "/path/for/this/endpoint"
}
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 85,
"timeOfSample": "2017-07-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 85,
"timeOfSample": "2017-07-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
}
}
}
}