# AWS IoT Core troubleshooting guide
**Help us improve this topic**
[Let us know what would help make it better](https://docs.aws.amazon.com//forms/aws-doc-feedback?hidden_service_name=IoT%20Docs&topic_url=http://docs.aws.amazon.com/en_us/iot/latest/developerguide/iot-core-troubleshoot.html)
This is the troubleshooting section for AWS IoT Core.
**Topics**
+ [Diagnosing connectivity issues](diagnosing-connectivity-issues.md)
+ [Diagnosing rules issues](diagnosing-rules.md)
+ [Diagnosing problems with shadows](diagnosing-shadows.md)
+ [Diagnosing Salesforce IoT input stream action issues](diagnosing-salesforce.md)
+ [Diagnosing Stream Limits](diagnosing-stream-limits.md)
+ [Troubleshooting device fleet disconnects](ota-troubleshooting-fleet-disconnects.md)
# Diagnosing connectivity issues
**Help us improve this topic**
[Let us know what would help make it better](https://docs.aws.amazon.com//forms/aws-doc-feedback?hidden_service_name=IoT%20Docs&topic_url=http://docs.aws.amazon.com/en_us/iot/latest/diagnosing-connectivity-issues.html)
A successful connection to AWS IoT requires:
+ A valid connection
+ A valid and active certificate
+ A policy that allows the desired connection and operation
## Connection
How do I find the correct endpoint?
+ The `endpointAddress` returned by `aws iot [describe-endpoint](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-endpoint.html) --endpoint-type iot:Data-ATS`
or
+ The `domainName` returned by `aws iot [describe-domain-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-domain-configuration.html) –-domain-configuration-name "domain_configuration_name"`
How do I find the correct Server Name Indication (SNI) value?
The correct SNI value is the `endpointAddress` returned by the **[describe-endpoint](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-endpoint.html)** or the `domainName` returned by the **[describe-domain-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-domain-configuration.html)** commands. It's the same address as the endpoint in the previous step. When connecting devices to AWS IoT Core, clients can send the [Server Name Indication (SNI) extension](https://tools.ietf.org/html/rfc3546#section-3.1), which is not required but highly recommended. To use features such as [multi-account registration](https://docs.aws.amazon.com//iot/latest/developerguide/x509-client-certs.html#multiple-account-cert), [custom domains](https://docs.aws.amazon.com//iot/latest/developerguide/iot-custom-endpoints-configurable-custom.html), and [VPC endpoints](https://docs.aws.amazon.com//iot/latest/developerguide/IoTCore-VPC.html), you must use the SNI extension. For more information, see [Transport Security in AWS IoT](transport-security.html).
How do I solve a connectivity issue that persists?
You can use AWS Device Advisor to help troubleshoot. Device Advisor's pre-built tests help you validate your device software against best practices for usage of [TLS](https://docs.aws.amazon.com/iot/latest/developerguide/protocols.html), [MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/protocols.html), [AWS IoT Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html), and [AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html).
Here is a link to the existing [Device Advisor](https://docs.aws.amazon.com/iot/latest/developerguide/device-advisor.html) content.
## Authentication
Devices must be [authenticated](client-authentication.md) to connect to AWS IoT endpoints. For devices that use [X.509 client certificates](x509-client-certs.md) for authentication, the certificates must be registered with AWS IoT and be active.
How do my devices authenticate AWS IoT endpoints?
Add the AWS IoT CA certificate to your client's trust store. Refer to the documentation on [Server Authentication in AWS IoT Core](x509-client-certs.html#server-authentication) and then follow the links to download the appropriate CA certificate.
What is checked when a device connects to AWS IoT?
When a device attempts to connect to AWS IoT:
1. AWS IoT checks for a valid certificate and Server Name Indication (SNI) value.
1. AWS IoT checks to see that the certificate used is registered with the AWS IoT Account and that it has been activated.
1. When a device attempts to perform any action in AWS IoT, such as to subscribe to or publish a message, the policy attached to the certificate it used to connect is checked to confirm that the device is authorized to perform that action.
How can I validate a correctly configured certificate?
Use the OpenSSL `s_client` command to test a connection to the AWS IoT endpoint:
```
openssl s_client -connect custom_endpoint.iot.aws-region.amazonaws.com:8443 -CAfile CA.pem -cert cert.pem -key privateKey.pem
```
For more information about using `openssl s_client`, see [OpenSSL s\$1client documentation](https://www.openssl.org/docs/man1.0.2/man1/openssl-s_client.html).
How do I check the status of a certificate?
+
**List the certificates**
If you don't know the certificate ID, you can see the status of all your certificates by using the `aws iot [list-certificates](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-certificates.html)` command.
+
**Show a certificate's details**
If you know the certificate's ID, this command shows you more detailed information about the certificate.
```
aws iot [describe-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-certificate.html) --certificate-id "certificateId"
```
+
**Review the certificate in the AWS IoT Console**
In the [AWS IoT console](https://console.aws.amazon.com/iot/home), in the left menu, choose **Secure**, and then choose **Certificates**.
Choose the certificate that you are using to connect from the list to open its detail page.
In the certificate's detail page, you can see its current status.
The certificate's status can be changed by using the **Actions** menu in the upper-right corner of the details page.
## Authorization
AWS IoT resources use [AWS IoT Core policies](iot-policies.md) to authorize those resources to perform [actions](iot-policy-actions.md). For an action to be authorized, the specified AWS IoT resources must have a policy document attached to it that grants permission to perform that action.
I received a `PUBNACK` or `SUBNACK` response from the broker. What do I do?
Make sure that there is a policy attached to the certificate you are using to call AWS IoT. All publish/subscribe operations are denied by default.
Make sure the attached policy authorizes the [actions](iot-policy-actions.md) you are trying to perform.
Make sure the attached policy authorizes the [resources](iot-action-resources.md) that are trying to perform the authorized actions.
I have an *AUTHORIZATION\$1FAILURE* entry in my logs.
Make sure that there is a policy attached to the certificate you are using to call AWS IoT. All publish/subscribe operations are denied by default.
Make sure the attached policy authorizes the [actions](iot-policy-actions.md) you are trying to perform.
Make sure the attached policy authorizes the [resources](iot-action-resources.md) that are trying to perform the authorized actions.
How do I check what the policy authorizes?
In the [AWS IoT console](https://console.aws.amazon.com/iot/home), in the left menu, choose **Security**, and then choose **Certificates**.
Choose the certificate that you are using to connect from the list to open its detail page.
In the certificate's detail page, you can see its current status.
In the left menu of the certificate's detail page, choose **Policies** to see the policies attached to the certificate.
Choose the desired policy to see its details page.
In the policy's details page, review the policy's **Policy document** to see what it authorizes.
Choose **Edit policy document** to make changes to the policy document.
## Security and identity
When you provide the server certificates for AWS IoT custom domain configuration, the certificates have a maximum of four domain names.
For more information, see [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#security-limits).
# Diagnosing rules issues
**Help us improve this topic**
[Let us know what would help make it better](https://docs.aws.amazon.com//forms/aws-doc-feedback?hidden_service_name=IoT%20Docs&topic_url=http://docs.aws.amazon.com/en_us/iot/latest/developerguide/diagnosing-rules.html)
This section describes some of the things to check when you encounter a problem with rule.
## Configuring CloudWatch Logs for troubleshooting
The best way to debug issues you are having with rules is to use CloudWatch Logs. When you enable CloudWatch Logs for AWS IoT, you can see which rules are triggered and their success or failure. You also get information about whether WHERE clause conditions match. For more information, see [Monitor AWS IoT using CloudWatch Logs](cloud-watch-logs.md).
The most common rules issue is authorization. The logs show if your role is not authorized to perform AssumeRole on the resource. Here is an example log generated by [fine-grained logging](configure-logging.md#fine-logging-cli):
```
{
"timestamp": "2017-12-09 22:49:17.954",
"logLevel": "ERROR",
"traceId": "ff563525-6469-506a-e141-78d40375fc4e",
"accountId": "123456789012",
"status": "Failure",
"eventType": "RuleExecution",
"clientId": "iotconsole-123456789012-3",
"topicName": "test-topic",
"ruleName": "rule1",
"ruleAction": "DynamoAction",
"resources": {
"ItemHashKeyField": "id",
"Table": "trashbin",
"Operation": "Insert",
"ItemHashKeyValue": "id",
"IsPayloadJSON": "true"
},
"principalId": "ABCDEFG1234567ABCD890:outis",
"details": "User: arn:aws:sts::123456789012:assumed-role/dynamo-testbin/5aUMInJH is not authorized to perform: dynamodb:PutItem on resource: arn:aws:dynamodb:us-east-1:123456789012:table/testbin (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: AccessDeniedException; Request ID: AKQJ987654321AKQJ123456789AKQJ987654321AKQJ987654321)"
}
```
Here is a similar example log generated by [global logging](configure-logging.md#global-logging-cli):
```
2017-12-09 22:49:17.954 TRACEID:ff562535-6964-506a-e141-78d40375fc4e
PRINCIPALID:ABCDEFG1234567ABCD890:outis [ERROR] EVENT:DynamoActionFailure
TOPICNAME:test-topic CLIENTID:iotconsole-123456789012-3
MESSAGE:Dynamo Insert record failed. The error received was User: arn:aws:sts::123456789012:assumed-role/dynamo-testbin/5aUMInJI is not authorized to perform: dynamodb:PutItem on resource: arn:aws:dynamodb:us-east-1:123456789012:table/testbin
(Service: AmazonDynamoDBv2; Status Code: 400; Error Code: AccessDeniedException; Request ID: AKQJ987654321AKQJ987654321AKQJ987654321AKQJ987654321).
Message arrived on: test-topic, Action: dynamo, Table: trashbin, HashKeyField: id, HashKeyValue: id, RangeKeyField: None, RangeKeyValue: 123456789012
No newer events found at the moment. Retry.
```
For more information, see [Viewing AWS IoT logs in the CloudWatch console](cloud-watch-logs.md#viewing-logs).
## Diagnosing external services
External services are controlled by the end user. Before rule execution, make sure that the external services you have linked to your rule are set up and have enough throughput and capacity units for your application.
## Diagnosing SQL problems
**If your SQL query is not returning the data you expect:**
+ **Review the logs for error messages.**
+
**Confirm that your SQL syntax matches the JSON document in the message.**
Review the object and property names used in the query with those used in the JSON document of the topic's message payload. For more information about the JSON formatting in SQL queries, see [JSON extensions](iot-sql-json.md).
+
**Check to see if the JSON object or property names include reserved or numeric characters.**
For more information about reserved characters in JSON object references in SQL queries, see [JSON extensions](iot-sql-json.md).
# Diagnosing problems with shadows
**Help us improve this topic**
[Let us know what would help make it better](https://docs.aws.amazon.com//forms/aws-doc-feedback?hidden_service_name=IoT%20Docs&topic_url=http://docs.aws.amazon.com/en_us/iot/latest/developerguide/diagnosing-shadows.html)
**Diagnosing shadows**
| Issue | Troubleshooting guidelines |
| --- | --- |
| A device's shadow document is rejected with Invalid JSON document. | If you are unfamiliar with JSON, modify the examples provided in this guide for your own use. For more information, see [Shadow document examples](device-shadow-document.md#device-shadow-document-syntax). |
| I submitted correct JSON, but none or only parts of it are stored in the device's shadow document. | Be sure you are following the JSON formatting guidelines. Only JSON fields in the desired and reported sections are stored. JSON content (even if formally correct) outside of those sections is ignored. |
| I received an error that the device's shadow exceeds the allowed size. | The device's shadow supports 8 KB of data only. Try shortening field names inside of your JSON document or simply create more shadows by creating more things. A device can have an unlimited number of things/shadows associated with it. The only requirement is that each thing name must be unique in your account. |
| When I receive a device's shadow, it is larger than 8 KB. How can this happen? | Upon receipt, the AWS IoT service adds metadata to the device's shadow. The service includes this data in its response, but it does not count toward the limit of 8 KB. Only the data for desired and reported state inside the state document sent to the device's shadow counts toward the limit. |
| My request has been rejected due to incorrect version. What should I do? | Perform a GET operation to sync to the latest state document version. When using MQTT, subscribe to the ./update/accepted topic to be notified about state changes and receive the latest version of the JSON document. |
| The timestamp is off by several seconds. | The timestamp for individual fields and the whole JSON document is updated when the document is received by the AWS IoT service or when the state document is published onto the ./update/accepted and ./update/delta message. Messages can be delayed over the network, which can cause the timestamp to be off by a few seconds. |
| My device can publish and subscribe on the corresponding shadow topics, but when I attempt to update the shadow document over the HTTP REST API, I get HTTP 403. | Be sure you have created policies in IAM to allow access to these topics and for the corresponding action (UPDATE/GET/DELETE) for the credentials you are using. IAM policies and certificate policies are independent. |
| Other issues. | The Device Shadow service logs errors to CloudWatch Logs. To identify device and configuration issues, enable CloudWatch Logs and view the logs for debug information. |
# Diagnosing Salesforce IoT input stream action issues
**Help us improve this topic**
[Let us know what would help make it better](https://docs.aws.amazon.com//forms/aws-doc-feedback?hidden_service_name=IoT%20Docs&topic_url=http://docs.aws.amazon.com/en_us/iot/latest/developerguide/diagnosing-salesforce.html)
## Execution trace
How do I see the execution trace of a Salesforce action?
See the [Monitor AWS IoT using CloudWatch Logs](cloud-watch-logs.md) section. After you have activated the logs, you can see the execution trace of the Salesforce action.
## Action success and failure
How do I check that messages have been sent successfully to a Salesforce IoT input stream?
View the logs generated by execution of the Salesforce action in CloudWatch Logs. If you see `Action executed successfully`, then it means that the AWS IoT rules engine received confirmation from the Salesforce IoT that the message was successfully pushed to the targeted input stream.
If you are experiencing problems with the Salesforce IoT platform, contact Salesforce IoT support.
What do I do if messages have not been sent successfully to a Salesforce IoT input stream?
View the logs generated by execution of the Salesforce action in CloudWatch Logs. Depending on the log entry, you can try the following actions:
`Failed to locate the host`
Check that the `url` parameter of the action is correct and that your Salesforce IoT input stream exists.
`Received Internal Server Error from Salesforce`
Retry. If the problem persists, contact Salesforce IoT Support.
`Received Bad Request Exception from Salesforce`
Check the payload you are sending for errors.
`Received Unsupported Media Type Exception from Salesforce`
Salesforce IoT does not support a binary payload at this time. Check that you are sending a JSON payload.
`Received Unauthorized Exception from Salesforce`
Check that the `token` parameter of the action is correct and that your token is still valid.
`Received Not Found Exception from Salesforce`
Check that the `url` parameter of the action is correct and that your Salesforce IoT input stream exists.
If you receive an error that is not listed here, contact AWS IoT Support.
# Diagnosing Stream Limits
**Troubleshooting "Stream limit exceeded for your AWS account"**
If you see `"Error: You have exceeded the limit for the number of streams in your AWS account."`, you can clean up the unused streams in your account instead of requesting a limit increase.
To clean up an unused stream that you created using the AWS CLI or SDK:
```
aws iot delete-stream –stream-id value
```
For more details, see [delete-stream](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-stream.html).
**Note**
You can use the `list-streams` command to find the stream IDs.
# Troubleshooting device fleet disconnects
**Help us improve this topic**
[Let us know what would help make it better](https://docs.aws.amazon.com//forms/aws-doc-feedback?hidden_service_name=IoT%20Docs&topic_url=http://docs.aws.amazon.com/en_us/iot/latest/developerguide/ota-troubleshooting-fleet-disconnects.html)
AWS IoT device fleet disconnects can happen for multiple reasons. This article explains how to diagnose a disconnect reason and how to handle disconnects caused by regular maintenance of AWS IoT service or a throttling limit.
**To diagnose the disconnect reason**
You can check the [AWSIotLogsV2](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html) log group in [CloudWatch](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html) to identify the disconnect reason in the `disconnectReason` field of the log entry.
You can also use AWS IoT's [lifecycle events](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html) feature to identify the disconnect reason. If you’ve subscribed to [lifecycle's disconnect event](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html#connect-disconnect) (`$aws/events/presence/disconnected/clientId`), you’ll get a notification from AWS IoT when the disconnect happens. You can identify the disconnect reason in the `disconnectReason` field of the notification.
For more information, see [CloudWatch AWS IoT log entries](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html) and [Lifecycle events](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html).
**To troubleshoot disconnects due to AWS IoT service maintenance**
Disconnects caused by AWS IoT's service maintenance are logged as `SERVER_INITIATED_DISCONNECT` in AWS IoT's lifecycle event and CloudWatch. To handle these disconnects, adjust your client-side setup to make sure your devices can be automatically reconnected to the AWS IoT platform.
**To troubleshoot disconnects due to a throttling limit**
Disconnects caused by a throttling limit are logged as `THROTTLED` in AWS IoT's lifecycle event and CloudWatch. To handle these disconnects, you can request [message broker limit increases](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits) as the device count grows.
For more information, see [AWS IoT Core Message Broker](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits).