Troubleshooting IoT Core MQTT Device Connection Issues

This guide covers common issues when connecting devices to ClearBlade IoT Core via MQTT, along with diagnostic steps and resolutions derived from real customer cases.

Connection Requirements Checklist

Before troubleshooting, verify your device meets all connection requirements:

**MQTT Broker URLs

IoT Core Standard (Multi-Tenant)

Standard IoT Core uses shared regional endpoints:

See Targeting Devices for the full list.

Warning: Legacy URLs (without -g5-) use the DigiCert G1 Root CA, which is being retired. Migrate to G5 URLs as soon as possible.

IoT Core Enterprise (Dedicated)

Enterprise environments have customer-specific MQTT URLs assigned during onboarding. These vary per customer and per environment (dev, staging, production).

If you are unsure of your MQTT broker URL, check with your ClearBlade account team or refer to the onboarding documentation provided for your environment.

For Enterprise authentication options beyond JWT, see MQTT Broker Authentication and Using other Tokens (Enterprise only).

Common Issues and Resolutions

1. TLS Handshake Failure — Connection Reset (RST)

Symptoms:

• Device receives a TCP RST during or immediately after sending a TLS Client Hello

• No SSL Alert is received — just a raw RST

• Wireshark/PCAP shows the Client Hello is identical between successful and failed attempts

• Connection works intermittently

Possible Causes:

Diagnostic Steps:

1. Capture a PCAP on the device side during both successful and failed connections

2. Verify TLS version in Client Hello is 1.2+

3. Note the exact timestamps (with timezone) of failed connections

4. Check if the device IP changes between retries (suggests carrier NAT / DPI)

5. Verify TLS connectivity using: openssl s_client -connect your-mqtt-broker-host:8883 -showcerts

6. Verify DNS resolution using: nslookup your-mqtt-broker-host

2. SSL Certificate Errors

Symptoms:

• SSL: no alternative certificate subject name matches target host name

• TLS handshake completes but certificate verification fails

• Error referencing wrong or missing Subject Alternative Name (SAN)

Possible Causes:

DigiCert G1 to G5 Migration Steps:

1. Download the DigiCert G5 Root CA appropriate for your device (ECC or RSA)

2. Update the device trust store or explicitly provide the G5 Root CA in your MQTT client configuration

3. Switch MQTT broker URL to the G5 endpoint

4. Test connectivity with the new configuration before rolling out to all devices

5. For Java (Paho) clients, use MqttConnectOptions.setSocketFactory() to supply the G5 Root CA

3. Authentication Failures (CONNACK Return Code 4)

Symptoms:

• MQTT CONNACK with return code 0x04 (Bad username or password)

• Device connects with shared credentials but fails with per-device JWT

• Broker log: errored in authentication, sending connack rc4 and closing

Possible Causes:

JWT Requirements for IoT Core MQTT:

Supported Algorithms: RS256 (RSA), ES256 (ECDSA P-256). See Creating key pairs for details.

4. Unexpected Disconnections

Symptoms:

• Device connects successfully but disconnects after some time

• Broker log: closing client due to error: read tcp i/o timeout

• +CMQTTCONNECT: 0,32 on cellular modem (error code 32 = server unavailable / connection lost)

Possible Causes:

5. Connection Rejected — Device or Registry Not Active

Symptoms:

• MQTT CONNACK with error

• Log: Registry is not active or Device is not active

Resolution:

1. Go to the ClearBlade IoT Core console

2. Verify the registry is enabled

3. Verify the device is enabled (not blocked)

4. If the device was recently created, wait a few seconds for propagation

6. Client ID Rejected (CONNACK Return Code 2)

Symptoms:

• MQTT CONNACK with return code 0x02

Resolution:

Verify the client ID follows the exact format: projects/{project_id}/locations/{region}/registries/{registry_id}/devices/{device_id}

Common mistakes:

• Wrong project_id (does not match the project owning the registry)

• Wrong region (e.g., us-central1 when registry is in europe-west1)

• Typo in registry_id or device_id

• Device ID does not exist in the registry

MQTT Error Code Quick Reference

CONNACK Return Codes (MQTT 3.1.1)

Diagnostic Steps

Run these from the device or a host on the same network as the device. Replace YOUR-MQTT-HOST with your actual MQTT broker hostname.

1. Verify TLS Connectivity: Use openssl s_client to connect to YOUR-MQTT-HOST on port 8883 with the -showcerts and -servername flags. Expected result: successful TLS handshake showing the DigiCert G5 certificate chain.

2. Verify DNS Resolution: Use nslookup on YOUR-MQTT-HOST. Expected result: resolves to a valid IP address.

3. Check Port Accessibility: Use nc -zv to test connectivity to YOUR-MQTT-HOST on port 8883. Expected result: connection succeeded.

4. Get Device Public IP: Useful for correlating device connections in server-side logs. Use a service like ifconfig.me to check the outbound IP.

5. Decode and Inspect Your JWT: Base64-decode the payload section of your JWT and verify: aud matches your project ID, exp is in the future, iat is within 10 minutes of current time.

Information to Provide When Opening a Support Ticket

To expedite resolution, include:

1. Project ID — e.g., my-project-12345

2. Region — e.g., europe-west3

3. Registry ID — e.g., my-device-registry

4. Device ID(s) — the specific device(s) having issues

5. Timestamp of failure — exact date, time, and timezone

6. Error message or code — CONNACK code, log messages, or modem output

7. PCAP capture (if TLS/network issue) — capture around the failure event

8. Device connection code snippet — the MQTT client configuration

9. Recent changes — any changes to registry config, device keys, firmware, or network in the last 24 hours

FAQ

Q: My device connects sometimes but not always. What is going on?

Intermittent failures usually point to network-level issues (carrier DPI, NAT timeouts, load balancer routing) rather than authentication or configuration problems. Capture PCAPs of both successful and failed attempts and compare. If the Client Hello is identical but only some attempts get RST, the issue is likely between the device and ClearBlade (network path), not at ClearBlade itself. Implement exponential backoff on reconnection.

Q: My JWT works in testing but fails on the device. Why?

Most common cause is base64 encoding. JWTs must use base64 URL encoding (alphabet: A-Z a-z 0-9 - _), not base64 standard encoding (alphabet: A-Z a-z 0-9 + /). Check for / or + characters in your token.

Q: Do I need to update my Root CA?

If you are using legacy URLs (without -g5-) on IoT Core Standard, yes — migrate to G5 URLs and the DigiCert G5 Root CA. For IoT Core Enterprise, ClearBlade will coordinate the G1-to-G5 certificate migration with you directly, including providing temporary G5 URLs for testing before cutover. See Targeting Devices for current Standard URLs and Root CA downloads.

Q: Can ClearBlade acquire more verbose logs for my MQTT device?

Yes. ClearBlade can enable verbose tracing for specific devices using broker trace commands. Open a support ticket with your full device path (projects/.../devices/DEVICE_ID) and ClearBlade engineers can enable enhanced logging for your device. HAProxy and load balancer logs may also be reviewed for TLS-level issues.

Q: My device disconnects exactly when the JWT expires. Is that expected?

Yes. When a JWT expires, ClearBlade automatically disconnects the MQTT session. MQTT does not support credential refresh inline. Your device must generate a new JWT and establish a new MQTT connection before the current JWT expires.

Q: I am getting reconnected too quickly errors. How long should I wait?

ClearBlade rate-limits rapid reconnections. Implement exponential backoff starting at 1 second, doubling on each retry, with a cap of 60 seconds. Adding random jitter helps avoid synchronized reconnection storms across device fleets.

Q: Can two connections use the same device ID simultaneously?

This is not possible in IoT Core Standard. It can be enabled with configuration changes in IoT Core Enterprise, but it is not recommended.