Share via

Troubleshoot cloud and deployment problems

  • Article

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

There are two main types of potential problems associated with the cloud and deployments: problems interacting with cloud-dependent azsphere commands and problems with devices not updating.

Troubleshoot cloud CLI commands

When you use cloud-dependent azsphere commands, the Azure Sphere Security Service performs operations on behalf of the command-line interface (CLI). To avoid exposing information about individual tenants, users, or devices—and thus risking an information leak—the Security Service in some cases returns a general error message, which the azsphere command passes through to you.

Here are some general troubleshooting tips for diagnosing and resolving such errors.

If you experience intermittent login errors on Windows, particularly with a personal Microsoft account, try using the --use-device-code option on login, and follow the instructions in the prompts:

azsphere login --use-device-code

This option is supported in the Windows SDK, version 20.04 Update 2 and later.

If a cloud-dependent command fails, first check the command itself:

  • Did you specify the right parameters?
  • If the command includes the ID for a device, device group, or other item, are you sure it's the correct id?
  • Are you trying to create a device group, product, or other item that already exists? Product names must be unique within a tenant. Device group names must be unique within a product and are not case sensitive.

Next, check your login identity and tenant:

  • Are you signed in to Azure Sphere with a valid login identity?
  • Are you accessing the correct tenant?
  • Have you changed your login identity? Each identity must be registered with Azure Sphere and must have an assigned role within the tenant. If you change your login—for example, by changing your email address—you must not only register the new identity, you must also ensure that the new identity is assigned a role.

Check your device:

  • Some commands require that a device is connected to your computer.

Finally, ensure that your user role in the tenant grants you permission to perform the operation:

  • If the command writes any data, you must be a Contributor or Administrator. Readers cannot write data, so they cannot create tenants, device groups, or products, add or delete device capabilities, upload image packages, or perform any other action that changes the information stored in the tenant or on the device.

Register-user error

If you are trying to use the command azsphere register-user, you will see an error message as this command has been deprecated. You should use alternative mechanisms to register a user.

Troubleshoot device updates

Over-the-air updates are an important part of the Azure Sphere security model. Problems can arise with both OS updates and deployment updates.

Troubleshoot OS updates

For a device to receive OS updates, the device must be connected to the internet. If your device appears to be running an outdated version of the Azure Sphere OS, verify your internet connection as described in Troubleshoot network problems.

If the device is running an OS earlier than 21.04, any board configuration images loaded onto the device must also be loaded into the cloud account of the tenant the device is claimed to.

Sideloading a board configuration onto a device allows initial ethernet configuration. However, for devices running a pre-21.01 OS, if that board configuration image was not included in the deployment, the device was prevented from performing any updates. This is because this configuration would result in removing the board configuration from the device and potentially losing internet connectivity. If this has occurred to one of your devices, you must upload the original board configuration image to the cloud account of the tenant the device is claimed to.

Troubleshoot deployment updates

For a device to obtain deployment updates, all of the following must be true:

  • It must be connected to the internet. If you suspect your device is not connected to the internet, see Troubleshoot network problems.
  • It must not have the application development capability.
  • It must be claimed into a tenant.
  • It must belong to a device group.
  • The device group to which it belongs must be targeted by a deployment.
  • The deployment must contain application images (and optionally a board configuration image) created by or on behalf of your organization.
  • The device group must have the UpdateAll update policy.

Azure Sphere supports a single tenant per device. This means that your organization controls all customer images that are deployed to your devices.

Removing the application development capability removes all sideloaded images that are not production signed.

Problems claiming a device

A device can be claimed only once. Once claimed, the device is permanently associated with the Azure Sphere tenant. If an error is reported when claiming your device to a tenant, one of the following may be the cause:

  • Check that you are using an unclaimed device that has not previously been used to create a tenant.
  • Check that you have the right permissions to execute the azsphere device claim command in the selected Azure Sphere tenant.
  • In the rare event that your Azure Sphere device was not registered during manufacture, contact your Microsoft representative to get it registered correctly. For more information, see Claim the chip.