Use the Smart Home Debugger
You can use the Smart Home Debugger to test and debug your Smart Home skill. By using the Smart Home debugger, your can view the ChangeReport, AddOrUpdateReport, and DeleteReport events that Alexa receives from your skill, including your JSON, and any processing errors. For more information about other test tools, see Test and Debug Your Smart Home Skill.
If you implement the Alexa.RTCSessionController interface in your Alexa skill, also see Use the Smart Home Debugger for WebRTC Skills.
You proactively report state to Alexa in ChangeReport
events. You identify the properties that you proactively report in your discovery response. For more information about change reports, see Understand State and Change Reporting.
Prerequisites
To use the Smart Home debugger, your Smart Home skill must send ChangeReport
, AddOrUpdateReport
, or DeleteReport
events to Alexa.
Accessing the Smart Home debugger
To view the Smart Home debugger
-
Open the Alexa developer console and log in.
-
Open the Smart Home skill associated with your Smart Home device.
-
Open the Test page.
-
Enable testing for the skill.
-
At the top of the page, select Device Log and Smart Home Debugger.
-
In the Smart Home Debugger section of the page, use the toggle to enable Smart Home debugger.
After you complete the procedure, when you send a ChangeReport, AddOrUpdateReport, or DeleteReport event to Alexa, the event information is added to the device log.
Viewing events
The Smart Home debugger shows the ChangeReport, AddOrUpdateReport, and DeleteReport events that Alexa receives from your skill, for the Amazon account that you used to sign in to the Alexa developer console. Each event in the device log contains a JSON document with details about the event that Alexa received. The following is an image of the Smart Home debugger.

If you encounter problems with the Smart Home debugger, use the Alexa Developer Contact Us page to let us know.
Example ChangeReport event with success
The following example shows the log in the Smart Home debugger for a ChangeReport
event that Alexa is able to process successfully.
{
"header": {
"customerId": "<customer id>",
"skillId": "<skill id>",
"skillStage": "development",
"eventType": "SmartHomeChangeReportSuccess",
"messageId": "<message id>",
"applianceId": "ALL"
},
"payload": {
"request": {
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"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
}
]
}
}
}
}
Example ChangeReport event with error
The following example shows the log in the Smart Home debugger for a ChangeReport
event that Alexa is unable to process successfully, because the request contains errors. For more information, see understanding event errors.
{
"header": {
"customerId": "<customer id>",
"skillId": "<skill id>",
"skillStage": "development",
"eventType": "SmartHomeChangeReportFailure",
"messageId": "<message id>",
"applianceId": "ALL"
},
"payload": {
"errors": [
{
"code": "Duplicate_Payload_Property",
"message": "duplicate property in the payload for brightness property"
}
],
"proactiveStateRequest": {
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"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
}
]
}
}
}
}
Understanding event errors
When your skill sends a ChangeReport, AddOrUpdateReport, or DeleteReport event to the Alexa event gateway, you receive an HTTP response from the gateway. For the full list of possible HTTP response codes, see Send Events to the Event Gateway.
When your skill receives a 202 Accepted
response from the gateway, it means that Alexa received your event request successfully. However, there might be errors in the event that prevent Alexa from processing it correctly. In that case, the debugger log contains a SmartHomeChangeReportFailure
, SmartHomeAddOrUpdateReportFailure
, or SmartHomeDeleteReportFailure
event that contains an array of errors in the payload.
Change report errors
The following table lists the error codes that you might see in the Smart Home debugger for a SmartHomeChangeReportFailure
.
Error Code | Description |
---|---|
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. |
AddOrUpdate report errors
The following table lists the error codes that you might see in the Smart Home debugger for a SmartHomeAddOrUpdateReportFailure
.
Error Code | Description |
---|---|
INVALID_REQUEST_EXCEPTION |
The request is invalid for one of the following reasons:
|
Delete report errors
The following table lists the error codes that you might see in the Smart Home debugger for a SmartHomeDeleteReportFailure
.
Error Code | Description |
---|---|
INVALID_REQUEST_EXCEPTION |
The request is invalid for one of the following reasons:
|