Troubleshooting

This section describes common issues you may encounter when using Cloud IoT Core.

If your device has trouble establishing a TLS connection to the Cloud IoT Core MQTT bridge, your environment may need the root certificate. You can install Google's root certificate from the Google Internet Authority site.

My device is unable to connect to the MQTT bridge

Your device tries to connect to the MQTT bridge, but the connection is unsuccessful. Unfortunately, the MQTT protocol does not allow for robust error reporting, so these issues can be tricky to debug.

Verify that you are able to connect via SSL to the MQTT bridge. Many corporate firewalls block port 8883. You can work with your internal IT team to allow access to port 8883, or you can use port 443 instead. Run one of the following commands (depending on the port you're using) to test the TLS connection to the MQTT bridge.
```
openssl s_client -connect mqtt.googleapis.com:8883
```
```
openssl s_client -connect mqtt.googleapis.com:443
```
If the connection to the MQTT endpoint is successful, this command prints certificate chain and server certificate information. It will stay connected and wait for input. This test confirms that you are able to establish a TLS connection to Cloud IoT Core.

Verify that you have Google's root certificates installed. You can download them from the Google Internet Authority site.
Use gcloud to check errors and verify that your devices and registries exist. Trying to connect with an invalid device ID will cause the connection to be closed immediately.
```
gcloud iot registries describe REGISTRY_ID \
      --project=PROJECT_ID \
      --region=REGION
```
```
 gcloud iot devices describe DEVICE_ID \
      --project=PROJECT_ID \
      --region=REGION \
      --registry=REGISTRY_ID
```
- The devices describe command may show additional error messages that can be used to help debug.
Verify that your device's credentials are not expired, using the devices describe command. If the credentials have no expiration set, they will never expire.
Check the exp claim on the JWT that you use to authenticate your device. The maximum lifetime of a token is 24 hours. For details, see Using JSON Web Tokens.
Verify that your device's clock is accurate. Your device's clock determines when to connect to the MQTT client and publish sensor data, so all of the devices in the network must be synchronized with the MQTT server. Clients can use the Google Public NTP Server to synchronize device clocks with Coordinated Universal Time (UTC).

My device is disconnected from the MQTT bridge

Your device is able to connect to the MQTT bridge, but is either disconnected immediately or disconnected unexpectedly. Note that very occasional disconnects are expected as servers are updated and load balanced.

Check the most recent error status of the device. Use the gcloud command below to review the most recent error status and message for a device. Be sure to note the timestamp; this field is not cleared and may refer to an earlier error.
```
gcloud iot devices describe DEVICE_ID \
  --project=PROJECT_ID \
  --region=REGION \
  --registry=REGISTRY_ID
```
- The error code number refers to a Google RPC error code.
Run the steps in the preceding section to ensure the device is able to connect.
If the device disconnects immediately after connecting, verify that your MQTT client library is using MQTT 3.1.1. Many libraries default to MQTT 3.1, which is not supported by Cloud IoT Core and will cause the device to be disconnected immediately. The version is typically set in the MQTT library's client options when first connecting.
- For example, if you are using the Paho Java client, you will have to call connectOptions.setMqttVersion(MqttConnectOptions.MQTT_VERSION_3_1_1);
If the device disconnects immediately after sending telemetry data, verify that you created a Cloud Pub/Sub topic for device telemetry with proper permissions set. See I'm not receiving telemetry data on Cloud Pub/Sub.
Check the exp claim on the JWT that you use to authenticate your device. The maximum lifetime of a token is 24 hours. For details, see Using JSON Web Tokens. After your JWT expires, the device will be disconnected and will have to reconnect. This is expected behavior; your device should create a new JWT and reconnect.
The MQTT bridge allows only a single connection for a given device ID. If a second device connects with the ID of a device that is already connected, the older device connection will be closed automatically.
Verify that your device is heartbeating frequently enough. MQTT client libraries allow the user to specify a heartbeat_interval, and your device will be disconnected if the MQTT bridge does not receive a message from the device in 1.5x that amount of time. Many client libraries will automatically send an empty message if no other messages have been sent (an MQTT PINGREQ message); however, your client library may not do this automatically. In addition, you can try increasing the heartbeat_interval in the MQTT client config to ensure that your device is able to keep up.

I'm not receiving telemetry data on Cloud Pub/Sub

Your device is connected and publishing messages to the MQTT bridge; however, you are not receiving them in the Cloud Pub/Sub topic. This usually means Cloud Pub/Sub is misconfigured or out of quota.

Use the preceding sections to verify that your device is able to connect and is not being disconnected. Client libraries provide connection and disconnection callbacks; use these to ensure that your device is successfully connecting.
On the IAM page in Google Cloud console, verify that the role Cloud IoT Core Service Agent appears in the Members list for the relevant project service account. (Look for the project service account that ends in @gcp-sa-cloudiot.iam.gserviceaccount.com.)

If the Cloud IoT Core Service Agent role does not appear in the Members list, use gcloud to add the cloudiot.serviceAgent role to the relevant project service account. This role includes permission to publish to Pub/Sub topics.

To find the PROJECT_ID and PROJECT_NUMBER, refer to this help article.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudiot.iam.gserviceaccount.com \
  --role=roles/cloudiot.serviceAgent
```
Note: You can also add the service account as a Pub/Sub Publisher to each individual topic, rather than assigning the role at the project level. To do so, use the Cloud Pub/Sub topics page in Google Cloud console. But for best results, assign the role at the project level instead.

Verify that the topics configured for your registry are correct:

gcloud iot registries describe REGISTRY_ID \
  --project=PROJECT_ID \
  --region=REGION

Verify that you have created a subscription for your topics for device telemetry. Cloud Pub/Sub will persist a message until all subscriptions have acknowledged it, but if there are no subscribers, your message will not be persisted.
- To list subscriptions:
```
gcloud pubsub topics list-subscriptions \
   projects/my-iot-project/topics/TOPIC_NAME
```
- To create a subscription for a topic:
```
gcloud pubsub subscriptions create \
   projects/my-iot-project/subscriptions/SUBSCRIPTION_NAME \
   --topic TOPIC_NAME
```
Check whether you are able to pull messages from your subscription via gcloud. If you are able to pull them but are not receiving them in your Pub/Sub client software, your client software may be misconfigured.
```
gcloud pubsub subscriptions pull \
   projects/my-iot-project/subscriptions/SUBSCRIPTION_NAME
```
If you configured your device registry to have multiple Pub/Sub topics, verify that the following are true:
- The MQTT or HTTP subfolder to which you're publishing telemetry data has a matching Pub/Sub topic
- The device registry has a default Pub/Sub topic
The default Pub/Sub topic will be used for published telemetry events that don't have a subfolder or if the specified subfolder doesn't have a matching topic. If you don't select a default Pub/Sub topic, these telemetry events will be lost.

You should add a default Pub/Sub topic when creating a device registry. If you didn't, you can add one using Google Cloud console, the gcloud iot registries update command, or the DeviceRegistry patch method. To make the new Pub/Sub topic the default for the device registry, don't specify a subfolder when you add the topic.

I'm receiving old telemetry data from Cloud Pub/Sub

You are able to receive telemetry events from Cloud Pub/Sub; however, your subscriber is receiving old events. This happens when Cloud Pub/Sub builds up a backlog. Cloud Pub/Sub guarantees that it will deliver each message at least once to each subscription for a topic, and if subscribers aren't consuming messages or acknowledging them, they will be redelivered. This can happen if your subscriber is not running, or is processing messages too slowly.

Verify that your Cloud Pub/Sub subscriber is acknowledging the messages it has processed.
If your subscriber has fallen behind, you can clear the backlog by deleting the subscriber and re-creating it.

Other Cloud Pub/Sub issues

Refer to the Cloud Pub/Sub documentation.