Azure IoT Operations: Fix Setup & Config Errors
Why This Is Happening
I've worked with dozens of teams trying to stand up Azure IoT Operations for the first time , and the single most common experience is this: you follow what looks like a straightforward deployment, and then nothing connects. Your MQTT broker isn't responding, your Arc cluster isn't recognized, or your data flows are silently dropping messages. The Azure portal gives you a green checkmark, but nothing on the edge is actually working.
Here's the honest truth: Azure IoT Operations is not a plug-and-play product. It's a sophisticated, Kubernetes-native data plane that sits at the intersection of your on-premises OT systems and the Azure cloud. Getting that bridge right takes careful setup. When it breaks, it breaks in ways that error messages rarely explain clearly.
The root causes I see most often fall into a few buckets. First, the Azure Arc-enabled Kubernetes cluster isn't properly configured before the IoT Operations deployment begins , and everything downstream inherits that problem silently. Second, teams underestimate the MQTT broker setup: the edge-native MQTT broker that powers Azure IoT Operations event-driven architectures has specific namespace, port, and TLS requirements that aren't obvious from a quick read of the docs. Third, version mismatches. As of 2026, Microsoft officially supports three GA versions simultaneously (currently 1.3.x, 1.2.x, and 1.1.x), and if your CLI version doesn't match your deployed version, commands fail in confusing ways.
There's also the offline scenario. Azure IoT Operations can operate offline for up to 72 hours, but during that window, some capabilities degrade. If your edge cluster lost cloud connectivity and then reconnected, you may be seeing stale state that needs a manual reconcile rather than a bug in your configuration.
Finally, the operational technology (OT) and IT divide creates real problems. Many of the teams I've seen struggle with Azure IoT Operations have OT engineers who know their industrial assets cold, and IT engineers who know Azure cold, but neither group fully owns the integration layer. The connector for OPC UA, Akri discovery services, and the Device Registry namespace configuration all live in that gap.
I know this can be genuinely frustrating, especially when it's blocking production workloads or a pilot you promised to leadership. The good news is that most issues are solvable without escalating to Microsoft Support. Let's work through them systematically. Browse all Microsoft fix guides →
The Quick Fix, Try This First
Before diving into multi-hour debugging sessions, run this check. The majority of Azure IoT Operations problems I've seen, probably 60% of them, come down to one of two things: your Arc cluster isn't in a healthy connected state, or your CLI version is out of sync with your deployed version. Both take under five minutes to verify.
Open your terminal and run the following to check your cluster's Arc connection status:
az connectedk8s show --name <your-cluster-name> --resource-group <your-rg> --query "connectivityStatus"You want to see "Connected" come back. If you see "Expired" or "Offline", that's your root cause right there. Your Azure IoT Operations instance cannot fully function without a healthy Arc connection, the cloud control plane can't push configuration down to your edge cluster.
Next, check your CLI version alignment. For the current 1.3.x GA release, you need CLI version 2.4.0. For 1.2.x, you need 2.3.0. For 1.1.x, you need 1.7.0. To check what you're running:
az version
az extension show --name azure-iot-ops --query "version"If those don't align with the table above, update your extension:
az extension update --name azure-iot-opsThen re-run whatever command was failing. In my experience, an outdated CLI extension causes more cryptic "resource not found" and "operation not supported" errors than any actual misconfiguration.
If your Arc connection is healthy and your CLI is current and things still aren't working, you need the full step-by-step below. But start here, it's fast and it catches more than you'd expect.
microsoft.iotoperations is stuck in a Failed provisioning state. Run az k8s-extension show --name azure-iot-operations --cluster-name <name> --resource-group <rg> --cluster-type connectedClusters to catch this.
Everything in Azure IoT Operations runs on top of an Azure Arc-enabled Kubernetes cluster. If that foundation has issues, nothing on top of it will work reliably. This is step one because I've watched teams spend days troubleshooting MQTT broker configs when the real problem was a cluster that Arc couldn't fully manage.
Start by verifying cluster connectivity from the Azure portal. Navigate to Azure Arc > Kubernetes clusters, find your cluster, and check that the status shows Connected, not just registered. A cluster can appear in the list while actually being in an expired or degraded state.
From the CLI, run a deeper health check:
az connectedk8s show \
--name <cluster-name> \
--resource-group <resource-group> \
--output tableLook at the connectivityStatus and provisioningState fields together. You want Connected and Succeeded respectively. If provisioningState shows Updating for more than 15 minutes, something is stuck. If it shows Failed, check your cluster's outbound internet connectivity, Arc agents need to reach specific Azure endpoints over port 443.
Also confirm that the Arc agents themselves are running on your cluster:
kubectl get pods -n azure-arcYou should see pods like clusterconnect-agent, config-agent, and metrics-agent all in a Running state. If any are in CrashLoopBackOff or Pending, that's blocking your entire Azure IoT Operations deployment, fix the Arc layer before touching anything IoT-specific.
What success looks like: All azure-arc namespace pods are Running, the portal shows your cluster as Connected, and the CLI returns provisioningState: Succeeded.
With a healthy Arc cluster confirmed, the next layer to check is the Azure IoT Operations Kubernetes extension itself. This is the mechanism that actually installs the IoT Operations components, including the MQTT broker, Akri connectors, and data flow engine, onto your cluster.
Check the extension state:
az k8s-extension show \
--name azure-iot-operations \
--cluster-name <cluster-name> \
--resource-group <resource-group> \
--cluster-type connectedClusters \
--query "{provisioningState:provisioningState, version:version, errorMessage:errorMessage}"If provisioningState is Failed, the errorMessage field is your starting point. Common errors here include insufficient node resources (the IoT Operations suite has real CPU and memory requirements, check your node capacity with kubectl describe nodes), missing prerequisite extensions, or RBAC permission gaps on the cluster.
For a failed extension, the cleanest recovery path is to delete it and redeploy. Don't try to patch a broken extension install, it rarely works:
az k8s-extension delete \
--name azure-iot-operations \
--cluster-name <cluster-name> \
--resource-group <resource-group> \
--cluster-type connectedClusters \
--yesWait for the delete to complete (watch the azure-iot-operations namespace drain in kubectl get ns), then follow the official deployment guide to reinstall. When redeploying, explicitly specify the version you want, don't let it default and then discover you're on a version your team hasn't tested.
What success looks like: The extension shows provisioningState: Succeeded and a valid version string. Pods in the azure-iot-operations namespace are all Running or Completed.
The MQTT broker is the beating heart of Azure IoT Operations. It runs natively on the edge cluster and powers the event-driven architecture that everything else depends on, the OPC UA connector publishes asset data to MQTT topics, and data flows subscribe to those topics to process and route messages. When the MQTT broker isn't working, your entire data pipeline is dead.
First, check that the MQTT broker pods are healthy:
kubectl get pods -n azure-iot-operations -l app=aio-brokerIf those pods aren't running, look at their logs before anything else:
kubectl logs -n azure-iot-operations -l app=aio-broker --tail=100The most common MQTT broker issues I see are certificate-related. Azure IoT Operations uses certificate management for secure MQTT connections, and if the certificate rotation has failed or the secrets aren't mounted correctly, the broker starts but rejects all connections. Check the secrets management state:
kubectl get secrets -n azure-iot-operationsLook for secrets related to broker TLS configuration. If they're missing or show as recently expired, that's your culprit. Azure IoT Operations includes built-in certificate management, but it requires the cluster to have cloud connectivity to rotate certificates. If your cluster was offline near a rotation deadline, you may have expired certs blocking connections.
To test raw MQTT connectivity once the broker pods are running, use a simple MQTT client from within the cluster:
kubectl run mqtt-test -it --image=eclipse-mosquitto --restart=Never \
-- mosquitto_pub -h aio-broker -p 1883 -t test/topic -m "hello"What success looks like: The MQTT broker pods are Running, TLS secrets are present and valid, and a test publish/subscribe completes without connection refused errors.
Data flows are how Azure IoT Operations moves, transforms, and contextualizes data between your edge assets and cloud destinations. A misconfigured data flow is often silent, it doesn't crash, it just doesn't process messages. This makes them tricky to debug.
Start from the operations experience web UI. Navigate to your Azure IoT Operations deployment in the Azure portal, then open the Operations Experience. From there, go to Data flows in the left nav. You'll see each data flow with a status indicator. A data flow showing as inactive or errored is your first signal something's wrong.
Click into the specific data flow and check the source and destination endpoint configuration. The most common issue is a misconfigured destination endpoint, particularly for cloud targets like Azure Event Hubs, Azure Event Grid, or Microsoft Fabric OneLake. Each of these requires specific connection strings, authentication settings, and in some cases schema configurations from the Device Registry schema registry.
For Event Hubs specifically, verify the connection string format. Azure IoT Operations expects the full connection string including the EntityPath for a specific Event Hub (not just the namespace-level connection string):
Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<policy>;SharedAccessKey=<key>;EntityPath=<eventhub-name>Also check that your data flow endpoint is using the correct schema. Azure IoT Operations uses the Device Registry schema registry to deserialize and serialize messages through data flows. If the schema version doesn't match what the OPC UA connector is publishing, messages will fail to process. Open the Device Registry in the Azure portal, find your asset, and verify the schema version assigned to the data flow matches what's currently being published.
For Microsoft Fabric OneLake destinations, confirm the workspace and lakehouse IDs are correct, and that the managed identity assigned to your IoT Operations instance has Contributor access to the target Fabric workspace.
What success looks like: Data flows show as active in the operations experience, and messages are appearing at the destination endpoint, verified in Event Hubs metrics, Fabric lakehouse file listings, or equivalent.
Azure IoT Operations is designed to keep running when your edge cluster loses cloud connectivity, and it does, for up to 72 hours. But that offline window creates a real resynchronization problem when connectivity returns. I've seen teams come in Monday morning after a weekend network outage to find their deployment in a degraded state even though it "reconnected" hours ago.
When your cluster reconnects after an offline period, the Arc agents need time to reconcile their state with the Azure control plane. During this reconciliation, some Azure IoT Operations operations will return errors or behave unexpectedly, this isn't a bug, it's the system catching up. Give it 10-15 minutes after connectivity is restored before assuming something is broken.
If the system doesn't self-heal after 15 minutes, force a reconcile of the Arc configuration:
az connectedk8s enable-features \
--name <cluster-name> \
--resource-group <resource-group> \
--features cluster-connect custom-locationsNext, check whether any data flows accumulated a backlog during the offline period. Azure IoT Operations processes and normalizes data at the edge before sending it to the cloud, but if the MQTT broker was publishing data during the offline window and data flows couldn't reach their cloud endpoints, there may be messages waiting in the broker queue. Check the broker queue depth:
kubectl exec -n azure-iot-operations <broker-pod-name> -- mosquitto_sub -t '$SYS/#' -C 20Also verify your Device Registry is back in sync. Namespaces that organize assets and devices can get out of sync during extended offline periods. Open the Azure portal, navigate to Device Registry, and confirm all expected assets and their associated namespaces are present and show correct metadata.
For deployments where multiple Azure IoT Operations instances share a single Device Registry namespace, which is a supported configuration, a post-outage reconnect for one instance can temporarily surface stale data from another instance's assets. If you're seeing asset data that doesn't match your current OT environment, a namespace refresh is likely needed.
What success looks like: Arc connectivity shows Connected, the operations experience reflects current asset states, and data is flowing to cloud endpoints with timestamps matching near-real-time.
Advanced Troubleshooting
If the five steps above haven't resolved your Azure IoT Operations issues, you're likely dealing with something at a deeper infrastructure layer, RBAC configuration, network topology, or problems specific to industrial asset connectivity through the OPC UA connector.
Azure IoT Operations RBAC and Managed Identity Issues
Azure IoT Operations uses managed identities to authenticate with cloud services. If you're seeing AuthorizationFailed errors in data flow logs or in the operations experience, the managed identity attached to your IoT Operations instance is missing role assignments. The identity needs specific roles depending on your cloud endpoints: Azure Event Hubs Data Sender for Event Hubs, Storage Blob Data Contributor for Data Lake Storage, and appropriate Fabric workspace roles for OneLake.
Check the current role assignments for your IoT Operations managed identity:
az role assignment list \
--assignee <managed-identity-client-id> \
--all \
--output tableAkri Connector and OPC UA Discovery Failures
The Akri services in Azure IoT Operations automatically discover devices and assets on your local network to reduce manual configuration overhead for OT users. When discovery isn't working, check the Akri agent pods:
kubectl get pods -n azure-iot-operations -l app.kubernetes.io/name=aio-akri-agent
kubectl logs -n azure-iot-operations -l app.kubernetes.io/name=aio-akri-agent --tail=200For the OPC UA connector specifically, the connector needs to reach your OPC UA servers over the network. If your industrial network uses firewalled VLANs between the Kubernetes nodes and the OT equipment, which is common in manufacturing environments, the connector will time out silently. Verify network path from a node to your OPC UA server on port 4840 (the default OPC UA port).
Layered Network and Secure Device Management
Azure IoT Operations supports secure management of devices in layered networks. If your environment uses a Purdue model network architecture (common in industrial settings), you may need to configure network proxies or use the ISA-95 zone configurations that Azure IoT Operations supports. This isn't something you can fix in the portal, it requires Kubernetes network policy configuration and potentially configuring the Arc agents to use an outbound proxy:
az connectedk8s connect \
--name <cluster-name> \
--resource-group <resource-group> \
--proxy-https https://<proxy-server>:<port> \
--proxy-http http://<proxy-server>:<port> \
--proxy-skip-range <local-subnet-cidr>Event Log and Metrics Analysis
Azure IoT Operations exposes metrics through its observability configuration. If you've set up the monitoring stack (the official docs cover this under "Configure observability and monitoring"), check your Prometheus metrics for MQTT broker message rates, data flow processing errors, and Akri discovery events. An MQTT broker that shows zero messages_received_total despite active OPC UA assets is telling you the connector isn't publishing, the problem is upstream of the broker.
For issues that only appear in specific time windows, look at the Kubernetes events alongside your metrics:
kubectl get events -n azure-iot-operations --sort-by='.lastTimestamp' | tail -50kubectl get all -n azure-iot-operations ready, support will ask for these immediately.
Prevention & Best Practices
Most Azure IoT Operations problems I see are predictable and preventable. The teams that run stable deployments share a few habits that the struggling teams don't. Let me give you the practical version of what those habits look like.
Stay current with supported versions. Microsoft supports exactly three GA versions at any given time. Right now that's 1.3.x, 1.2.x, and 1.1.x. The 1.0.x series (versions 2411 through 2503) is already out of support. Running an out-of-support version means you get no security patches, no bug fixes, and Microsoft Support won't help you troubleshoot it. Set a calendar reminder every quarter to check whether your version is still in the supported window.
Test the offline recovery path before you need it. Azure IoT Operations can run offline for up to 72 hours, but you don't want to discover your recovery procedure during a real outage. In a test environment, deliberately cut the cluster's outbound connectivity for 30-60 minutes, then restore it and time how long full functionality takes to return. Document that process. It's much better to learn that your certificate rotation window is narrower than expected during a planned test than during a production outage.
Keep your Device Registry namespaces clean. Each Azure IoT Operations instance uses a single namespace for assets and devices, and multiple instances can share a single namespace. Namespace sprawl and stale asset registrations cause subtle bugs, especially with schema versioning in data flows. Build a regular process to audit registered assets against your actual OT environment.
Version-pin your Azure IoT Operations CLI extension. The CLI version must match your deployment version (1.3.x needs CLI 2.4.0, etc.). In CI/CD pipelines and shared admin environments, floating CLI versions cause breakage. Pin explicitly and update intentionally.
- Set up Azure Monitor alerts on your Arc cluster connectivity status, know before your users do when connectivity degrades
- Tag all Azure IoT Operations resources with a
versiontag matching your deployed version; makes audit and support conversations much faster - Keep one clean staging cluster at the same version as production to safely test configuration changes before applying them to your live edge deployment
- Document your Akri discovery configuration for each asset type in your OT environment, when assets are replaced or firmware is updated, knowing your original discovery config prevents hours of re-setup
Frequently Asked Questions
What exactly is Azure IoT Operations and how does it differ from older Azure IoT Hub setups?
Azure IoT Operations is a Kubernetes-native unified data plane for the edge, it runs directly on Azure Arc-enabled Kubernetes clusters at your site, not in the cloud. Unlike older IoT Hub architectures where devices connect directly to cloud endpoints, Azure IoT Operations processes and normalizes data at the edge before sending it up. It includes a built-in edge MQTT broker, OPC UA connectors through Akri services, and data flow transformation capabilities, all of which run locally. It connects natively to Azure Event Hubs, the MQTT broker in Azure Event Grid, and Microsoft Fabric on the cloud side, but the heavy lifting happens on-premises. This matters a lot in manufacturing and industrial environments where sending raw machine data to the cloud before filtering it would be wasteful or too slow for real-time decisions.
My Azure IoT Operations cluster went offline over the weekend, how long can it run disconnected and what breaks?
Azure IoT Operations can operate offline for a maximum of 72 hours. During that window, your edge MQTT broker keeps running, Akri connectors keep collecting data from local OT assets, and any locally-configured data flows continue processing. What degrades is anything that requires cloud connectivity: sending data to Event Hubs, Fabric, or Data Lake endpoints will queue up or drop depending on your data flow configuration, and certificate rotation can't happen if it falls due during the outage. After the 72-hour mark, Microsoft's documentation notes that further degradation may occur. When connectivity is restored, give the system at least 10-15 minutes to reconcile its state with the Azure control plane before assuming something is permanently broken.
Which Azure IoT Operations versions are still supported, I don't want to be running something outdated?
As of early 2026, Microsoft supports three GA versions simultaneously: 1.3.x (current patch 1.3.38, CLI version 2.4.0), 1.2.x (current patch 1.2.189, CLI version 2.3.0), and 1.1.x (current patch 1.1.59, CLI version 1.7.0). The 1.0.x series, all releases from version 2411 through 2503, is no longer within the support window and won't receive security or bug fix patches. If you're on 1.0.x, migrating is a priority. The supported version window shifts each time a new minor version ships, so check the official Azure IoT Operations versioning page quarterly to stay current.
How do I connect Azure IoT Operations to Microsoft Fabric for real-time dashboards?
The connection goes through a data flow with a Microsoft Fabric OneLake endpoint as the destination. In the operations experience web UI, create a new data flow, set your MQTT topic as the source (where your OPC UA connector or other asset connectors publish data), and add a Fabric OneLake endpoint as the destination. You'll need your Fabric workspace ID and lakehouse ID, both of which you can find in the Fabric portal URL when you have the lakehouse open. Make sure the managed identity assigned to your Azure IoT Operations instance has at least Contributor access on the target Fabric workspace, missing this role assignment is the most common reason the data flow authenticates but fails to write. Once connected, Microsoft Fabric can build real-time dashboards from the incoming asset data, which is exactly the pattern the anomaly detection use case in the official docs describes.
The operations experience web UI shows my assets but the data flows aren't picking up their messages, what's wrong?
This is almost always a schema mismatch between what the OPC UA connector is publishing and what the data flow is expecting. Azure IoT Operations uses the Device Registry schema registry to serialize and deserialize messages through data flows. If you updated an asset's OPC UA node configuration or the asset firmware changed its data format, the schema version in Device Registry may no longer match. Open Device Registry in the Azure portal, find the affected asset, and check its schema version. Then open your data flow and verify it references the same schema version. A secondary cause is that the data flow's source MQTT topic subscription doesn't match the topic the connector is publishing to, OPC UA connector topic paths are based on the asset name and server endpoint, and if either was renamed, your subscription is no longer matching any messages.
Can multiple Azure IoT Operations instances share the same Device Registry namespace, and does that cause problems?
Yes, multiple Azure IoT Operations instances can share a single Device Registry namespace, this is an officially supported configuration, useful when you have multiple edge clusters managing the same pool of industrial assets across a site. The risk is that asset metadata updates from one instance can affect what the other instance sees, which causes confusion when debugging data flow issues. Each instance uses the shared namespace for storing asset information in the cloud, and the schema registry within it is accessible to all instances pointing at that namespace. If you're running into unexpected asset state changes that you can't trace to your own operations, check whether another instance sharing your namespace has recently modified assets there. For most deployments, keeping namespaces per-instance is cleaner, only share namespaces when you have a deliberate multi-instance asset management strategy in place.