Troubleshooting in Azure IoT Central

This article includes troubleshooting guidance for device connectivity issues and data export configuration issues in your IoT Central applications.

Device connectivity issues

This section helps you determine if your data is reaching IoT Central.

If you haven't already done so, install the az cli tool and azure-iot extension.

To learn how to install the az cli, see Install the Azure CLI.

To install the azure-iot extension, run the following command:

az extension add --name azure-iot

Note

You may be prompted to install the uamqp library the first time you run an extension command.

When you've installed the azure-iot extension, start your device to see if the messages it's sending are making their way to IoT Central.

Use the following commands to sign in the subscription where you have your IoT Central application:

az login
az account set --subscription <your-subscription-id>

To monitor the telemetry your device is sending, use the following command:

az iot central diagnostics monitor-events --app-id <iot-central-app-id> --device-id <device-name>

If the device has connected successfully to IoT Central, you see output similar to the following example:

Monitoring telemetry.
Filtering on device: device-001
{
    "event": {
        "origin": "device-001",
        "module": "",
        "interface": "",
        "component": "",
        "payload": {
            "temp": 65.57910343679293,
            "humid": 36.16224660107426
        }
    }
}

To monitor the property updates your device is exchanging with IoT Central, use the following preview command:

az iot central diagnostics monitor-properties --app-id <iot-central-app-id> --device-id <device-name>

If the device successfully sends property updates, you see output similar to the following example:

Changes in reported properties:
version : 32
{'state': 'true', 'name': {'value': {'value': 'Contoso'}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac
': 200}, 'brightness': {'value': {'value': 2}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac': 200}, 'p
rocessorArchitecture': 'ARM', 'swVersion': '1.0.0'}

If you see data appear in your terminal, then the data is making it as far as your IoT Central application.

If you don't see any data appear after a few minutes, try pressing the Enter or return key on your keyboard, in case the output is stuck.

If you're still not seeing any data appear on your terminal, it's likely that your device is having network connectivity issues, or isn't sending data correctly to IoT Central.

Check the provisioning status of your device

If your data isn't appearing in the CLI monitor, check the provisioning status of your device by running the following command:

az iot central device registration-info --app-id <iot-central-app-id> --device-id <device-name>

The following output shows an example of a device that's blocked from connecting:

{
  "@device_id": "v22upeoqx6",
  "device_registration_info": {
    "device_status": "blocked",
    "display_name": "Environmental Sensor - v22upeoqx6",
    "id": "v22upeoqx6",
    "instance_of": "urn:krhsi_k0u:modelDefinition:w53jukkazs",
    "simulated": false
  },
  "dps_state": {
    "error": "Device is blocked from connecting to IoT Central application. Unblock the device in IoT Central and retry. Learn more:
https://aka.ms/iotcentral-docs-dps-SAS",
    "status": null
  }
}
Device provisioning status Description Possible mitigation
Provisioned No immediately recognizable issue. N/A
Registered The device hasn't yet connected to IoT Central. Check your device logs for connectivity issues.
Blocked The device is blocked from connecting to IoT Central. Device is blocked from connecting to the IoT Central application. Unblock the device in IoT Central and retry. To learn more, see Device status values.
Unapproved The device isn't approved. Device isn't approved to connect to the IoT Central application. Approve the device in IoT Central and retry. To learn more, see Device status values
Unassigned The device isn't assigned to a device template. Assign the device to a device template so that IoT Central knows how to parse the data.

Learn more about Device status values in the UI and Device status values in the REST API.

Error codes

If you're still unable to diagnose why your data isn't showing up in monitor-events, the next step is to look for error codes reported by your device.

Start a debugging session on your device, or collect logs from your device. Check for any error codes that the device reports.

The following tables show the common error codes and possible actions to mitigate.

If you're seeing issues related to your authentication flow:

Error code Description Possible Mitigation
400 The body of the request isn't valid. For example, it can't be parsed, or the object can't be validated. Ensure that you're sending the correct request body as part of the attestation flow, or use a device SDK.
401 The authorization token can't be validated. For example, it has expired or doesn't apply to the request's URI. This error code is also returned to devices as part of the TPM attestation flow. Ensure that your device has the correct credentials.
404 The Device Provisioning Service instance, or a resource such as an enrollment doesn't exist. File a ticket with customer support.
412 The ETag in the request doesn't match the ETag of the existing resource, as per RFC7232. File a ticket with customer support.
429 The service is throttling operations. For specific service limits, see IoT Hub Device Provisioning Service limits. Reduce message frequency, split responsibilities among more devices.
500 An internal error occurred. File a ticket with customer support to see if they can help you further.

Detailed authorization error codes

Error Sub error code Notes
401 Unauthorized 401002 The device is using invalid or expired credentials. DPS reports this error.
401 Unauthorized 400209 The device is either waiting for approval by an operator or an operator has blocked it.
401 IoTHubUnauthorized The device is using expired security token. IoT Hub reports this error.
401 IoTHubUnauthorized DEVICE_DISABLED The device is disabled in this IoT hub and has moved to another IoT hub. Reprovision the device.
401 IoTHubUnauthorized DEVICE_BLOCKED An operator has blocked this device.

File upload error codes

Here's a list of common error codes you might see when a device tries to upload a file to the cloud. Remember that before your device can upload a file, you must configure device file uploads in your application.

Error code Description Possible Mitigation
403006 You've exceeded the number of concurrent file upload operations. Each device client is limited to 10 concurrent file uploads. Ensure the device promptly notifies IoT Central that the file upload operation has completed. If that doesn't work, try reducing the request timeout.

Unmodeled data issues

When you've established that your device is sending data to IoT Central, the next step is to ensure that your device is sending data in a valid format.

To detect which categories your issue is in, run the most appropriate Azure CLI command for your scenario:

  • To validate telemetry, use the preview command:

    az iot central diagnostics validate-messages --app-id <iot-central-app-id> --device-id <device-name>
    
  • To validate property updates, use the preview command:

    az iot central diagnostics validate-properties --app-id <iot-central-app-id> --device-id <device-name>
    

You may be prompted to install the uamqp library the first time you run a validate command.

The three common types of issue that cause device data to not appear in IoT Central are:

  • Device template to device data mismatch.
  • Data is invalid JSON.
  • Old versions of IoT Edge cause telemetry from components to display incorrectly as unmodeled data.

Device template to device data mismatch

A device must use the same name and casing as used in the device template for any telemetry field names in the payload it sends. The following output shows an example warning message where the device is sending a telemetry value called Temperature, when it should be temperature:

Validating telemetry.
Filtering on device: sample-device-01.
Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).
[WARNING] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['Temperature']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'. 

A device must use the same name and casing as used in the device template for any property names in the payload it sends. The following output shows an example warning message where the property osVersion isn't defined in the device template:

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
[WARNING]  [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['osVersion']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'.

A device must use the data types defined in the device template for any telemetry or property values. For example, you see a schema mismatch if the type defined in the device template is boolean, but the device sends a string. The following output shows an example error message where the device using a string value for a property that's defined as a double:

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
Validating telemetry.
Filtering on device: sample-device-01.
Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).
[ERROR] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg]  Datatype of telemetry field 'temperature' does not match the datatype double. Data sent by the device : curr_temp. For more information, see: https://aka.ms/iotcentral-payloads

The validation commands also report an error if the same telemetry name is defined in multiple interfaces, but the device isn't IoT Plug and Play compliant.

If you prefer to use a GUI, use the IoT Central Raw data view to see if something isn't being modeled.

Screenshot that shows the raw data view in an IoT Central application.

When you've detected the issue, you may need to update device firmware, or create a new device template that models previously unmodeled data.

If you chose to create a new template that models the data correctly, migrate devices from your old template to the new template. To learn more, see Manage devices in your Azure IoT Central application.

Invalid JSON

If there are no errors reported, but a value isn't appearing, then it's probably malformed JSON in the payload the device sends. To learn more, see Telemetry, property, and command payloads.

You can't use the validate commands or the Raw data view in the UI to detect if the device is sending malformed JSON.

IoT Edge version

To display telemetry from components hosted in IoT Edge modules correctly, use IoT Edge version 1.2.4 or later. If you use an earlier version, telemetry from components in IoT Edge modules displays as _unmodeleddata.

Data export managed identity issues

You're using a managed identity to authorize the connection to an export destination. Data isn't arriving at the export destination.

Before you configure or enable the export destination, make sure that you complete the following steps:

  • Enable the managed identity for the IoT Central application. To verify that the managed identity is enabled, go to the Identity page for your application in the Azure portal or use the following CLI command:

    az iot central app identity show --name {your app name} --resource-group {your resource group name}
    
  • Configure the permissions for the managed identity. To view the assigned permissions, select Azure role assignments on the Identity page for your app in the Azure portal or use the az role assignment list CLI command. The required permissions are:

    Destination Permission
    Azure Blob storage Storage Blob Data Contributor
    Azure Service Bus Azure Service Bus Data Sender
    Azure Event Hubs Azure Event Hubs Data Sender
    Azure Data Explorer Admin

    If the permissions were not set correctly before you created the destination in your IoT Central application, try removing the destination and then adding it again.

  • Configure any virtual networks, private endpoints, and firewall policies.

Note

If you're using a managed identity to authorize the connection to an export destination, IoT Central doesn't export data from simulated devices.

To learn more, see Export data.

Data export destination connection issues

The export definition page shows information about failed connections to the export destination:

Screenshot that shows an example export error.

Next steps

If you need more help, you can contact the Azure experts on the Microsoft Q&A and Stack Overflow forums. Alternatively, you can file an Azure support ticket.

For more information, see Azure IoT support and help options.