Azure Sphere Integrated: Fix Setup & Migration Issues
Why This Is Happening
I've talked to dozens of IoT engineers in the past few months who all have the same look on their faces: slight panic, a browser tab open to Microsoft's retirement announcement, and a notepad full of questions they're not sure how to ask. If you're running Azure Sphere devices in production and you're only now digging into what "Azure Sphere Integrated" actually means for your fleet , you're not alone, and you're not late. But you do need to move.
Here's the short version of what happened. On March 20, 2026, Microsoft officially announced the planned retirement of Azure Sphere, including the MT3620 microcontroller-based platform that powered the original generation of Azure Sphere hardware. The MT3620 silicon itself goes end-of-life on July 31, 2026 , that's a hard date. Extended support for the Azure Sphere OS and Security Service runs until July 31, 2031, but after that point, your devices stop receiving OS updates, application updates, bug fixes, and security patches. Device attestation and authentication services will also cease, which means your devices won't be able to connect to Azure IoT or other upstream services at all.
The confusion most people hit is the distinction between Azure Sphere (Legacy) and Azure Sphere (Integrated). These aren't just marketing rename, they represent two genuinely different operational models for your tenant, your catalogs, and how your devices authenticate and receive updates. Azure Sphere (Legacy) is the older interface: it'll reach retirement on September 27, 2027, and Microsoft has already started pausing Legacy access by default on all newly created catalogs as of May 2025. If you spun up a new catalog recently and something stopped working, that's almost certainly why.
Microsoft's error messages in this space are, to put it charitably, not helpful. You'll often see generic authentication failures, silent update failures, or device attestation errors that give you an error code but no actionable next step. That's because the underlying cause, Legacy access being paused, a tenant not yet migrated, a certificate chain that's broken post-migration, isn't surfaced clearly in the portal or the CLI output.
The good news is that the path forward is documented and achievable. Azure Sphere (Integrated) is the target architecture, and the migration path involves evaluating your catalogs, pausing Legacy operations once you've confirmed you're clear, and aligning your silicon strategy with PSA/SESIP Level 3+ certified alternatives to the MT3620 for any hardware you're redesigning. The sections below walk through each of those steps in concrete detail.
Browse all Microsoft fix guides →The Quick Fix, Try This First
If your Azure Sphere devices suddenly stopped receiving updates, your catalog operations are throwing errors, or you migrated to Azure Sphere (Integrated) and now nothing authenticates, the single fastest thing you can check is whether Legacy access has been paused on your catalog.
As of May 2025, Microsoft changed the default behavior: newly created Azure Sphere catalogs ship with Legacy access paused. If you're using any tooling, scripts, or workflows that still talk to the Legacy interface, they will fail immediately with no graceful degradation. The error won't always tell you "Legacy is paused", it may just look like an authentication error or a silent timeout.
Here's what you do. Sign in to the Azure portal at portal.azure.com. Navigate to your Azure Sphere resource. In the left-hand menu, find the Azure Sphere (Legacy) section. You'll see a toggle or status indicator showing whether Legacy access is currently enabled or paused. If it says "Paused," that's your culprit.
You can temporarily re-enable Legacy access from that same panel, this buys you time to identify and migrate any remaining workflows that depend on it. The important word there is "temporarily." Microsoft's guidance is explicit: once you've confirmed that Legacy is no longer needed, pause it again. Leaving it open is a security exposure, not just a configuration preference.
While you have Legacy re-enabled, run through your CI/CD pipelines, your build scripts, and any monitoring agents that interact with your Azure Sphere tenant. Check whether they're calling the Legacy API surface or the Integrated one. The quickest way to audit this is to search your scripts for calls to the legacy tenant endpoint formats and flag them for migration.
If your issue isn't Legacy access at all, if your devices haven't received an OS update recently and you're sure Legacy isn't involved, skip ahead to Step 3, where we cover verifying and manually triggering the SDK update and OS version check.
Before you do anything else, you want a baseline. You need to know what OS version your attached devices are running and whether they're current. Without this, you're troubleshooting blind.
Connect your Azure Sphere device to your development machine. Open a terminal with the Azure CLI installed. Run the following command:
az sphere device show-os-versionThis returns the OS version string currently installed on the connected device. Write it down. Cross-reference it against the release notes on Microsoft's Azure Updates page, the release naming format is year.month, so version 25.05 would be May 2025. If your device is multiple releases behind and you haven't changed anything, it typically means one of three things: the device hasn't had a stable internet connection during an update window, the catalog it's registered in has something misconfigured, or, and this is increasingly common post-retirement-announcement, the device is in an evaluation OS feed that's out of sync with the production feed.
Also check which version of the Azure Sphere SDK is installed on your development machine. Note that this command is only available in the legacy azsphere tool, not in the Azure CLI extension:
azsphere show-versionIf this command fails with "command not found" or returns a version older than 24.x, your SDK needs updating before anything else will work reliably. Jump to Step 3 after confirming the OS version.
If the OS version comes back current and matching the latest release, the issue is likely in your catalog configuration or in the Legacy/Integrated migration state, continue to Step 2.
This is the step that trips up most teams who've been running Azure Sphere devices for years. Migration from Azure Sphere (Legacy) to Azure Sphere (Integrated) isn't automatic. You have to evaluate each catalog, understand what operations are still using the Legacy interface, and then deliberately make the switch.
Start in the Azure portal. Navigate to your Azure Sphere resource group, then select each catalog you own. Look for the Legacy interface status. If the catalog was created before May 2025, Legacy access is likely still enabled by default on that catalog. If it was created after, it's paused by default.
The migration process isn't a single button press, it's a validation loop. Here's the sequence Microsoft recommends and that actually works in practice:
- Pause Legacy access on the catalog in the portal.
- Run your normal device management operations, OTA updates, deployments, attestation checks.
- If something breaks, you've found a remaining Legacy dependency. Re-enable Legacy, fix the dependency, then pause again.
- Repeat until nothing breaks when Legacy is paused.
- At that point, you're on Integrated. Keep Legacy paused permanently.
For enterprise teams with dozens of catalogs, this manual loop is painful. Build a simple test script that exercises your most critical catalog operations (device list, deployment push, OTA trigger) against each catalog with Legacy paused, and capture any failures. That gives you a concrete migration checklist rather than a guessing game.
Remember: Azure Sphere (Legacy) retires on September 27, 2027. That sounds far away right now. It isn't. Factor in testing, hardware validation, and any firmware changes, and you want to be done with this migration at least six months before that date.
Unlike OS updates, which push automatically to internet-connected devices, SDK updates and the Azure Sphere extension for the Azure CLI require manual installation. This surprises a lot of people. I've seen engineers spend hours debugging what turned out to be a stale SDK installation that was misinterpreting new API responses from the Azure Sphere Security Service.
On Windows, the SDK installer is available from the Azure Sphere documentation download page. Run it like any standard MSI, you don't need to uninstall the previous version first. After installation completes, verify with:
azsphere show-versionOn Linux, the process involves the same installer script documented in the official Linux SDK setup instructions. Make sure you're pulling from the official source and not a cached copy from your package manager that might be outdated.
The Azure Sphere extension for the Azure CLI is a separate update and people forget this constantly. The extension can be out of date even when the CLI itself is current. To check and update it, run:
az extension update --name azure-sphereIf you get an error saying the extension isn't installed, install it fresh:
az extension add --name azure-sphereOne thing Microsoft documents but buries: breaking changes to the Azure Sphere extension for the Azure CLI can happen out-of-band from a regular Azure Sphere OS release. This means your extension can go from working to broken without any OS release happening. Check the Release Updates page on Microsoft Learn whenever you see unexpected CLI failures, there may be an extension update you missed.
After updating, re-run the OS version check from Step 1 to confirm the new SDK is communicating correctly with your device.
If you're running production devices and you want to catch OS-level breaking changes before they hit your entire fleet, this step is not optional, it's essential. Microsoft's Retail Evaluation program lets you receive new OS builds two full weeks before they roll out to all devices globally. That's two weeks to catch a regression before it affects your customers.
I know it sounds like extra work. It is, slightly. But I've seen what happens when teams skip it: a new OS release changes a behavior that their high-level app depends on, devices in the field start behaving unexpectedly, and the engineering team is scrambling to roll back or patch without any rollback path because OTA is one-directional.
To enroll a device in the Retail Evaluation feed, the official documentation points to the "Set up devices for OS evaluation" section on Microsoft Learn. The process uses the Azure Sphere CLI and requires that the device be in a catalog you control. You change the OS feed assignment for the device group:
az sphere device-group update \
--catalog <YourCatalogName> \
--resource-group <YourResourceGroup> \
--product <YourProductName> \
--device-group <YourDeviceGroupName> \
--os-feed RetailEvalDevices in that group will then receive evaluation builds two weeks early. Keep a dedicated test device group enrolled in RetailEval and your production group on Retail. Promote builds from RetailEval to Retail only after you've validated app compatibility. This single practice catches the vast majority of OTA-related regressions before they become incidents.
Given the retirement timeline, and the fact that Azure Sphere OS updates are ongoing through 2031, staying on top of OS changes is more important now than ever. Don't skip this.
This step is less about fixing something broken today and more about preventing something catastrophic tomorrow. The MT3620 silicon goes end-of-life on July 31, 2026. That's a hard date. After that point, Microsoft will not produce or support new MT3620 components.
If your product roadmap has new hardware revisions planned, even minor ones, any board that still uses the MT3620 will need a redesign. The official guidance from Microsoft is to evaluate PSA/SESIP Level 3+ certified silicon as a guideline for finding alternatives with comparable security properties. This certification level aligns with the security posture Azure Sphere was designed to deliver, so it's the right benchmark to target.
There's also a practical purchasing consideration. If you need additional MT3620 stock for existing products that will continue in production through the extended support window (devices that don't need redesign but need replacement units, for example), you need to express purchasing intent through the official distributor, Avnet, before July 31, 2026. After that date, you won't be able to procure the silicon at all.
For the software stack on new silicon, Microsoft recommends evaluating Azure IoT libraries for device firmware development, and FIPS 140-3 compliant cryptographic libraries for at-rest and in-transit data encryption. For device management and attestation on the new hardware, the replacement stack looks like this:
- Device and certificate management: Azure IoT Hub with Azure Device Registry (ADR) and X.509 Certificate Management (currently in Public Preview)
- Device data plane: Azure IoT Hub
- Device attestation: Microcontrollers with a PSA Certified Attestation API
- Firmware updates: Device Update for Azure IoT Hub
Start this evaluation now. Hardware redesigns take longer than anyone expects, and six months from now you don't want to be trying to source a new MCU under deadline pressure.
Advanced Troubleshooting
If you've worked through the five steps above and you're still hitting problems, the issues you're facing are likely in one of three deeper areas: RBAC configuration for Azure Sphere ARM resources, device attestation failures tied to the Integrated migration, or enterprise network policies that are interfering with the Azure Sphere Security Service (AS3) communication.
Azure RBAC for Azure Sphere ARM Resources
Azure Sphere (Integrated) uses Azure Resource Manager (ARM) for resource management, which means it inherits Azure's full RBAC model. This is actually an improvement over Legacy, more granular access control, but it also means that users or service principals that had access under Legacy may not have the correct role assignments for the new ARM-based resources. If catalog operations are failing with permission errors after migration, check the role assignments on the Azure Sphere resource in the portal under Access Control (IAM). The specific roles needed for Azure Sphere Integrated operations are documented under the "Overview Azure RBAC for Azure Sphere ARM resources" section in Microsoft's official docs.
Device Attestation Failures
After migrating a catalog to Integrated, some devices will fail attestation temporarily, especially if they were last checked in under the Legacy interface. The fix here is to trigger a re-attestation by ensuring the device connects to the internet and is assigned to an active deployment group in the Integrated catalog. If re-attestation continues to fail, check whether the device's certificate chain is valid. Devices that were provisioned very early in the Azure Sphere program sometimes have certificate chains that need refreshing, and the process for that is detailed in the AS3 REST API documentation.
Network-Level Blocks
Enterprise environments with strict egress filtering will sometimes block the Azure Sphere Security Service endpoints. The AS3 communicates over standard HTTPS (port 443), but to specific hostnames that your firewall team may not have whitelisted. Check with your network team that the Azure Sphere service endpoints are reachable from the network segment where your devices operate. If devices are behind a proxy, ensure the proxy is configured to pass through Azure Sphere authentication traffic without TLS inspection, certificate pinning in the Azure Sphere OS does not play nicely with MITM-style TLS inspection proxies.
Diagnostic Data Collection
Azure Sphere supports diagnostic data collection that can be invaluable when you can't reproduce an issue locally. The official documentation covers the "Collect and report diagnostic data" workflow under the Monitor section. Enable this on affected devices and review the output before escalating to Microsoft.
az sphere device show-os-version from an affected device. That context will cut your support resolution time significantly.
Prevention & Best Practices
The teams who handle Azure Sphere (Integrated) migration smoothly share one trait: they planned for it months before they had to. The teams who struggle are the ones who treated the retirement announcement as something to handle later. Here's how to be in the first group going forward.
Keep your Azure Sphere extension for the Azure CLI updated on a regular cadence, at minimum monthly, ideally tied to your standard infrastructure maintenance windows. Breaking changes can arrive out-of-band from an OS release, and a stale extension is one of the most common root causes of mysterious CLI failures. Add it to your team's standard tooling-update checklist.
For any fleet larger than ten devices, maintain at least one device group enrolled in the Retail Evaluation OS feed. Treat that group the same way you treat a staging environment for software, changes go there first, and you have two weeks to validate before they hit production. This is especially important now, when the OS update cadence is continuing through 2031 and you need ongoing assurance that each update is compatible with your application stack.
Document your Legacy dependencies before you start migrating, not during. Pause Legacy access once, observe what breaks, write down every system that threw an error. That list becomes your migration checklist. Migrating blind, assuming everything is on Integrated when you haven't actually verified it, is how production incidents happen at 2 AM.
For hardware teams: start your MT3620 replacement evaluation now, not in Q3. Silicon qualification cycles are long. PSA/SESIP Level 3+ certified MCUs exist across multiple silicon vendors, but your firmware team will need time to evaluate the SDK compatibility, re-implement your application layer, and test attestation against Azure IoT Hub with the new certificate chain. Budget that time honestly.
- Run
az extension update --name azure-sphereas part of your monthly infrastructure maintenance cycle, don't wait for something to break. - Enroll at least one device group in the Retail Evaluation OS feed today, even if you don't have a specific reason to yet; you'll thank yourself when the next OS release drops.
- Set a hard internal deadline of Q1 2027 for completing your Legacy-to-Integrated catalog migration, that gives you nine months of buffer before the September 2027 Legacy retirement date.
- Contact Avnet now to express purchasing intent for MT3620 stock if you need additional units, because that option disappears entirely after July 31, 2026.
Frequently Asked Questions
What exactly is Azure Sphere Integrated and how is it different from Legacy?
Azure Sphere (Integrated) is the current-generation operational model for managing Azure Sphere devices and catalogs. It uses Azure Resource Manager (ARM) for all resource management, which means it plugs into the same RBAC, monitoring, and governance tooling you use for the rest of your Azure estate. Azure Sphere (Legacy) was the original management interface, it used its own tenant and API surface that sat outside the standard ARM model. The functionality overlaps heavily, but the underlying plumbing is different. Legacy is retiring on September 27, 2027, and as of May 2025, new catalogs ship with Legacy access paused by default. If you're running existing workflows against the Legacy interface, they will fail once Legacy is paused, so migration to Integrated is not optional.
My Azure Sphere catalog started throwing errors and I didn't change anything, what happened?
Almost certainly, Legacy access was paused on your catalog, either automatically (if the catalog was newly created after May 2025) or by an admin in your organization. Sign in to portal.azure.com, navigate to your Azure Sphere resource, and look for the Azure Sphere (Legacy) section in the left-hand menu. If it shows "Paused," that's your answer. You can re-enable Legacy temporarily while you identify and migrate whichever workflows depend on it, but the long-term fix is migrating those workflows to the Integrated interface. Also check that your Azure Sphere extension for the Azure CLI is up to date, run az extension update --name azure-sphere, because out-of-band extension updates can also introduce breaking changes without a formal OS release.
Is Azure Sphere being shut down completely? Will my devices stop working?
Not immediately, and not all at once, but yes, on a defined timeline. Microsoft announced the retirement of Azure Sphere on March 20, 2026. The MT3620 silicon goes end-of-life on July 31, 2026, meaning no new units will be produced or available after that date. Extended support for the Azure Sphere OS and Security Service continues until July 31, 2031, so devices already in the field keep receiving OS updates, security patches, and bug fixes through that date. After July 31, 2031, those updates stop entirely, and device attestation and authentication services cease, which will break connectivity to Azure IoT and other upstream services. If you have hardware in the field that will still be operating after 2031, you need a hardware redesign plan now.
How do I check which Azure Sphere OS version my device is running?
Connect your device to your development machine, open a terminal, and run az sphere device show-os-version using the Azure CLI with the Azure Sphere extension installed. This returns the current OS version string on the connected device. OS updates are delivered automatically to internet-connected devices, so if your device is behind and you haven't changed network configuration, it likely hasn't had a clean connection during an update window. Release versions follow a year.month format, 25.05 means May 2025. Cross-reference the output against the What's New page on Microsoft Learn to see how far behind you are and whether any recent releases included security patches that your device is missing.
What should I replace the MT3620 with when it goes end-of-life?
Microsoft's official guidance is to evaluate PSA/SESIP Level 3+ certified silicon as a like-for-like replacement from a security posture standpoint, this is the certification tier that matches the MT3620's security properties. Beyond the silicon itself, the recommended stack for device management is Azure IoT Hub with Azure Device Registry (ADR) for device and certificate management (X.509, currently in Public Preview), Device Update for Azure IoT Hub for firmware OTA, and a PSA Certified Attestation API-capable MCU for device attestation. For firmware development, Microsoft recommends evaluating the Azure IoT libraries and FIPS 140-3 compliant cryptographic libraries for your encryption needs. Start this evaluation early, silicon qualification and firmware porting both take longer than expected, and the MT3620 becomes unavailable for purchase after July 31, 2026.
Do SDK updates install automatically like OS updates do?
No, and this trips people up constantly. The Azure Sphere OS updates push automatically to internet-connected devices, but SDK updates and the Azure Sphere extension for the Azure CLI require manual installation on your development machine. For the SDK on Windows, download and run the installer from the official Azure Sphere documentation page. For the CLI extension, run az extension update --name azure-sphere from your terminal. Visual Studio and Visual Studio Code extensions also need manual updates through their respective extension managers. Microsoft can push breaking changes to the CLI extension out-of-band from a formal OS release, so it's worth checking for extension updates whenever you see unexpected CLI behavior, don't assume a working CLI means an up-to-date CLI.