Common issues and resolutions for Azure IoT Edge for Linux on Windows
Applies to:
IoT Edge 1.5
IoT Edge 1.4
Important
IoT Edge 1.5 LTS and IoT Edge 1.4 LTS are supported releases. IoT Edge 1.4 LTS is end of life on November 12, 2024. If you are on an earlier release, see Update IoT Edge.
Use this article to help resolve common issues that can occur when deploying IoT Edge for Linux on Windows solutions.
Installation and Deployment
The following section addresses the common errors when installing the EFLOW MSI and deploying the EFLOW virtual machine. Ensure you have an understanding of the following EFLOW concepts:
- Azure IoT Edge for Linux on Windows prerequisites
- Nested virtualization for Azure IoT Edge for Linux on Windows
- Networking configuration for Azure IoT Edge for Linux on Windows
- PowerShell functions for IoT Edge for Linux on Windows
| Error | Error Description | Solution |
|---|---|---|
| HNS API version X doesn't meet minimum version | EFLOW uses HCS/HNS to create the virtual machine on client SKUs. The minimum HNS version its 9.2. | If you're using a Windows version 20H1 or later, the HCS/HNS API should meet the requirement. If you're using Windows Client RS5 (17763), verify you have the latest Windows update. |
| Can't find WSSDAGENT service! WssdAgent is unreachable, update has failed. |
The WSSDAgent is the EFLOW component that creates and manages the lifecycle of the VM. WSSDAgent runs a service on the Windows host OS. If the service isn't running, the VM communication and lifecycle fails. | Verify the WSSDAgent service is running on the Windows host OS by opening an elevated PowerShell session and running the command Get-Service -Name wssdagent. If WSSDAgent isn't running, try starting the service manually using the cmdlet: Start-Service -name WSSDAgent. If it doesn't start, share the content under C:\ProgramData\wssdagent. |
| Expected image '$vhdPathBackup' is missing | When installing EFLOW current release (CR), the user can provide the data partition size using the vmDataSize. If specified, EFLOW resizes the VHDX. The error occurs if the VHDX file isn't found during resizing. | Verify the VHDX file wasn't deleted or moved from the original location. |
| Installation of Hyper-V, Hyper-V Management PowerShell or OpenSSH failed. Please install manually and restart deployment. Aborting... | EFLOW installation has required prerequisites to deploy the virtual machine. If one the prerequisites aren't met, the Deploy-Eflow cmdlet fails. |
Ensure that all required prerequisites are met. PowerShell: Close PowerShell session and open a new one. If you have multiple installations, make sure to have the correct module imported. Try a different version of PowerShell. Hyper-V: For more information EFLOW Hyper-V support, see Azure IoT Edge for Linux on Windows Nested Virtualization. OpenSSH: If you're using your own custom installation, check customSsh parameter during deployment. |
| $feature isn't available in this Windows edition. $featureversion could not be enabled. Please add '$featureversion' optional feature in settings and restart the deployment. |
When deploying EFLOW, if one of the prerequisites it's not met, the installer tries to install it. If this feature isn't available or the feature installation fails, the EFLOW deployment fails. | Ensure that all required prerequisites are met. PowerShell: Close PowerShell session and open a new one. If you have multiple installations, make sure to have the correct module imported. Try a different version of PowerShell. Hyper-V: For more information EFLOW Hyper-V support, see Azure IoT Edge for Linux on Windows Nested Virtualization. OpenSSH: If you're using your own custom installation, check customSsh parameter during deployment. |
| Hyper-V properties indicate the Hyper-V component is not functional (property HyperVRequirementVirtualizationFirmwareEnabled is false) Hyper-V properties indicate the Hyper-V component is not functional (property HyperVisorPresent is false). Hyper-V core services not running (vmms, vmcompute, hvhost). Ensure Hyper-V is configured properly and capable of starting virtual machines. |
These errors are related to Hyper-V virtualization technology stack and services. The EFLOW virtual machine requires several Hyper-V services in order to create and run the virtual machine. If one of these services isn't available, the installation fails. | For more information EFLOW Hyper-V support, see Azure IoT Edge for Linux on Windows Nested Virtualization. |
| wssdagent unreachable, please retry... | The WSSDAgent is the EFLOW component that creates and manages the lifecycle of the VM. WSSDAgent runs a service on the Windows host OS. | Verify the WSSDAgent service is running on the Windows host OS by opening an elevated PowerShell session and running the command Get-Service -Name wssdagent. If WSSDAgent isn't running, try starting the service manually using the cmdlet: Start-Service -name WSSDAgent. If it doesn't start, share the content under C:\ProgramData\wssdagent. |
| Virtual machine configuration could not be retrieved from wssdagent | Find the EFLOW configuration yaml files under the EFLOW root installation folder. For example, if the default installation directory was used, the configuration files should be in the C:\Program Files\Azure IoT Edge\yaml directory. | Check if the directory was deleted or moved. If the directory isn't available, the VM can't be created. EFLOW reinstallation is needed. |
| An existing virtual machine was detected. To redeploy the virtual machine, please uninstall and re-install $eflowProductName. Virtual machine '$name' already exists. You much remove '$name' virtual machine first. |
During EFLOW deployment, the installer checks if there's an EFLOW VM created from previous installations. In some cases, if the installation fails in its final steps, the VM was created and it's still running in the Windows host OS. | Make sure to completely uninstall EFLOW before starting a new installation. If you want to remove the Azure IoT Edge for Linux on Windows installation from your device, use the following commands. 1. In Windows, open Settings 2. Select Add or Remove Programs 3. Select Azure IoT Edge LTS app 4. Select Uninstall |
| Creating storage vhd (file: $($config["imageNameEflowVm"])) failed | Error when creating or resizing the EFLOW virtual machine VHDX. | Check EFLOW installation logs C:\Program Files\Azure IoT Edge and WSSDAgent logs C:\ProgramData\wssdagent for more information. |
| Error: Virtual machine creation failed! Failed to retrieve virtual machine name. |
Error related to virtual machine creation by WSSDAgent. Installer will try removing the VM and mark the installation as failed. | Verify the WSSDAgent service is running on the Windows host OS by opening an elevated PowerShell session and running the command Get-Service -Name wssdagent. If WSSDAgent isn't running, try starting the service manually using the cmdlet: Start-Service -name WSSDAgent. If it doesn't start, share the content under C:\ProgramData\wssdagent. |
| This Windows device does not meet the minimum requirements for Azure EFLOW. Please refer to https://aka.ms/AzEFLOW-Requirements for system requirements | During EFLOW deployment, the Deploy-EFlow PowerShell cmdlet checks that all the prerequisites are met. Specifically, Windows SKUs are checked (Windows Server 2019, 2022, Windows Client Professional, or Client Enterprise) and the Windows version is at least 17763. | Verify you're using a supported Windows SKU and version. If using Windows version 17763, ensure to have all the updates applied. |
| Not enough memory available. | There isn't enough RAM memory to create the EFLOW VM with the allocated VM memory. By default, the virtual machine has 1024 MB assigned. The Windows host OS needs to have at least X MB free to assign that memory to the VM. | Check the Windows host OS memory available and use the memoryInMb parameter during Deploy-Eflow for custom memory assignment. For more information about Deploy-EFlow PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Not enough CPU cores available. | There isn't enough CPU cores available to create the EFLOW VM with the allocated cores. By default, the virtual machine will have one core assigned. The Windows host OS needs to have at least one core to assign that core to the EFLOW VM. | Check the Windows host OS CPU cores available and use the cpuCore parameter during Deploy-Eflow for custom memory assignment. For more information about Deploy-EFlow PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Not enough disk space is available on drive '$drive'. | There isn't enough storage available to create the EFLOW VM with the allocated storage size. By default, the VM will use ~18 GB of storage. The Windows host OS needs to have at least 18 GB of free storage to assign that storage to the EFLOW VM VHDX. | Check the Windows host free storage available and use the vmDiskSize parameter during Deploy-Eflow for custom storage size. For more information about Deploy-EFlow PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Signature is not valid (file: $filePath, signature status: ${signature.Status}) Signature is missing (file: $filePath)! could not track signature to the microsoft root certificate |
The signature of the file can't be found or it's invalid. EFLOW PSM and EFLOW updates are all signed using Microsoft certificates. If the Azure code or Azure CA certificates are not available in the Windows host OS, the validation fails. | Verify all contents were downloaded from official Azure sites. Also, if the necessary certificates aren't part of the Windows host, check Install EFLOW necessary certificates. |
Provisioning and IoT Edge runtime
The following section addresses the common errors when provisioning the EFLOW virtual machine and interact with the IoT Edge runtime. Ensure you have an understanding of the following EFLOW concepts:
- What is Azure IoT Hub Device Provisioning Service?
- Understand the Azure IoT Edge runtime and its architecture
- Troubleshoot your IoT Edge device
| Error | Error Description | Solution |
|---|---|---|
| Action aborted by user | For some of the EFLOW PowerShell cmdlets, there's user interaction and confirmation needed. | - |
| Error, device connection string not provided. Only the device connection string for ManualConnectionString provisioning may be specified. |
Incorrect parameters used when using ManualConnectionString device provisioning. | For more information about the Provision-EflowVm PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| IoT Hub Hostname, Device ID, and/or identity cert/pk parameters for ManualX509 provisioning not specified Device connection string, scope ID, registration ID, and symmetric key may not be specified for DpsX509 provisioning Certificate and private key file for ManualX509 provisioning not found (expected at $identityCertPath and $identityPrivKeyPath) |
Incorrect parameters used when using ManualX509 device provisioning. | For more information about Provision-EflowVm PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Scope ID for DpsTpm provisioning not specified Only scope ID and registration ID (optional) for DpsTpm provisioning may be specified |
Incorrect parameters used when using DpsTpm device provisioning. | For more information about Provision-EflowVm PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Scope ID, registration ID or symmetric key missing for DpsSymmetricKey provisioning globalEndpoint not specified Only scope ID, registration ID or symmetric key for DpsSymmetricKey provisioning may be specified |
Incorrect parameters used when using DpsSymmetricKey device provisioning. | For more information about Provision-EflowVm PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Virtual machine does not exist, deploy it first | The EFLOW MSI was installed, however the EFLOW virtual machine was never deployed. | Deploy the EFLOW VM using the Deploy-Eflow PowerShell cmdlet. |
| Aborting, iotedge was previously provisioned (headless mode)! | The EFLOW VM was previously provisioned and headless mode isn't supported when reprovisioning. | The issue is fixed and now -headless mode is supported with reprovisioning |
| Provisioning aborted by user | The EFLOW VM was previously provisioned and the user needs to confirm they want to reprovision. | User must accept reprovisioning to continue with the provisioning process. |
| Failed to provision Failed to provision config.toml. Please provision manually. iotedge service not running after provisioning, please investigate manually |
The EFLOW provisioning information was correctly configured inside the EFLOW VM, but the IoT Edge daemon was not able to provision the device with the cloud provisioning service. | Check the Azure IoT Edge runtime logs. First, connect to the EFLOW virtual machine using the Connect-EflowVm PowerShell cmdlet then follow Troubleshoot your IoT Edge device to retrieve the IoT Edge logs. |
| Unexpected return from 'sudo iotedge list' Retrieving iotedge check output from: "$vmName" |
The execution of sudo iotedge list command inside the EFLOW VM returned an unexpected payload. Generally this is related to IoT Edge service not running correctly inside the EFLOW VM. |
Check the Azure IoT Edge runtime logs. First, connect to the EFLOW virtual machine using the Connect-EflowVm PowerShell cmdlet then follow Troubleshoot your IoT Edge device to get the IoT Edge logs. |
| TPM 2.0 is required to enable DpsTpm | TPM passthrough only works with TPM 2.0 compatible hardware. This could be caused by a physical TPM or if the EFLOW VM is running using nested virtualization using vTPM on the Windows host OS. | Make sure the Windows host OS has a valid TPM 2.0, check Enable TPM 2.0 on your PC. |
| TPM provisioning information not available! | The TPM passthrough binary inside the EFLOW VM could not get the TPM information from the Windows host OS. This error is probably related to a communication error with the EFLOWProxy. | Ensure that the EFLOW Proxy Service service is running using the PowerShell cmdlet Get-Service -name "EFLOW Proxy Service". If not running, check the Event logs. Open the Event Viewer > Application and service logs -> Azure IoT Edge for Linux on Windows. |
Interaction with the VM
The following section addresses the common errors when interacting with the EFLOW virtual machine, and configure the EFLOW device passthrough options. Ensure you have an understanding of the following EFLOW concepts:
- PowerShell functions for IoT Edge for Linux on Windows
- GPU acceleration for Azure IoT Edge for Linux on Windows
| Error | Error Description | Solution |
|---|---|---|
| Can't process request, EFLOW VM is OFF! | When trying to apply a configuration to the EFLOW virtual machine, the VM must be turned on. If the EFLOW VM is off, then the SSH channel will fail, and no communication is possible with the VM. | Start the EFLOW VM using the Start-EflowVm PowerShell cmdlet. For more information about the Start-EflowVm cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Virtual machine name could not be retrieved from wssdagent Error: More than one virtual machine found |
The WSSDAgent service couldn't find the EFLOW virtual machine. | Verify the EFLOW VM is started and running, use the PowerShell cmdlet Start-EflowVm. If using a client SKU, use the hcsdiag list cmdlet and find the line that has wssdagent after the GUID of the VM then check the state. If using a server SKU, go to Hyper-V manager and verify there's a VM with the name Windows-hostname-EFLOW then check the state. |
| Unable to connect virtual machine with SSH. Aborting.. | The Windows host OS could not establish an SSH connection with the EFLOW VM to execute the necessary commands or copy files. Generally, this issue is related to a networking problem between Windows and the virtual machine. | Try the PowerShell cmdlet Get-EflowVmAddr and check if the IP4Address assigned to the VM is correct. For more information about networking configurations, see Azure IoT Edge for Linux on Windows networking. |
| Unexpected return stats from virtual machine | The execution of Get-EflowVm PowerShell cmdlet checks the status of the virtual machine. If the communication with the virtual machine fails, or some of the Linux bash commands inside the VM fail, the cmdlet fails. |
Check the EFLOW VM connection using Connect-EflowVm PowerShell cmdlet and try manually running the VM stats bash commands inside the VM. |
| TPM provisioning was not enabled! | To get the TPM provisioning information for the TPM, the EFLOW TPM passthrough must be enabled. If TPM passthrough isn't enabled, the cmdlet fails. | Enable TPM passthrough before getting the TPM information. Use the Set-EflowVmFeature PowerShell cmdlet to enable the TPM passthrough. For more information about Set-EflowVmFeature PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Unknown feature '$feature' is provided. | The Set-EflowVmFeature cmdlet supports DpsTpm and Defender as the two features that can be enabled or disabled. | For more information about Set-EflowVmFeature PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Unsupported DDA Type: $gpuName | Currently, GPU DDA is only supported for NVIDIA Tesla T4 and NVIDIA A2. If the user provides another GPU name, the GPU passthrough fails. | Verify all the GPU prerequisites are met. For more information about EFLOW GPU support, check Azure IoT Edge for Linux on Windows GPU passthrough. |
| Invalid GPU configuration requested, Passthrough enabled but requested gpuCount == $gpuCount GPU PassthroughType '$gpuPassthroughType' not supported by '$script:WssdProviderVmms' WssdProvider Requested GPU configuration cannot be supported by Host, GPU '$gpuName' not available Requested GPU configuration cannot be supported by Host, not enough GPUs available - Requested($gpuCount), Available($($selectedGpuDevice.Count)) Requested GPU configuration cannot be supported by Host, GPU PassthroughType '$gpuPassthroughType' not supported Invalid GPU configuration requested, Passthrough disabled but gpuCount > 0" |
These errors are generally related to one or more the GPU dependencies not being met. | Make sure all the GPU prerequisites are met. For more information about EFLOW GPU support, check Azure IoT Edge for Linux on Windows GPU passthrough. |
Networking
The following section addresses the common errors related to EFLOW networking and communication between the EFLOW virtual machine and the Windows host OS. Ensure you have an understanding of the following EFLOW concepts:
- Azure IoT Edge for Linux on Windows networking
- Networking configuration for Azure IoT Edge for Linux on Windows
| Error | Error Description | Solution |
|---|---|---|
| Installation of virtual switch failed The virtual switch '$switchName' of type '$switchType' was not found |
When creating the EFLOW VM, there's a check that the virtual switch provided exists and has the correct type. If using no parameter, the installation uses the default switch provided by the Windows client. | Check that the virtual switch being used is part of the Windows host OS. You can check the virtual switches using the PowerShell cmdlet Get-VmSwitch. For more information about networking configurations, see Azure IoT Edge for Linux on Windows networking. |
| The virtual switch '$switchName' of type '$switchType' is not supported on current host OS |
When using Windows client SKUs, external/default switches are supported. However, when using Windows Server SKUs, external/internal switches are supported. | For more information about networking configurations, see Azure IoT Edge for Linux on Windows networking. |
| Cannot set Static IP on ICS type virtual switch (Default Switch) | The default switch is a virtual switch that's provided in the Windows client SKUs after installing Hyper-V. This switch already has a DHCP server for IP4Address assignation and for security reasons doesn't support a static IP. | If using the default switch, you can either use the Get-EflowVmAddr cmdlet or use the hostname of the EFLOW VM to get the VM IP4Address. If using the hostname, try using Windows-hostname-EFLOW.mshome.net. For more information about networking configurations, see Azure IoT Edge for Linux on Windows networking. |
| $dnsServer is not a valid IP4 address | The Set-EflowVmDnsServers cmdlet expects a list of valid IP4Addresses | Verify you provided a valid list of addresses. You can check the Windows host OS DNS servers by using the PowerShell cmdlet ipconfig /all and then looking for the entry DNS Servers. For example, if you wanted to set two DNS servers with IPs 10.0.1.2 and 10.0.1.3, use the Set-EflowVmDnsServers -dnsServers @("10.0.1.2", "10.0.1.3") cmdlet. |
| Could not retrieve IP address for virtual machine Virtual machine name could not be retrieved, failed to get IP/MAC address Failed to acquire MAC address for virtual machine Failed to acquire IP address for virtual machine Unable to obtain host routing. Connectivity test to $computerName failed. wssdagent does not have the expected vnet resource provisioned. Missing EFLOW-VM guest interface for ($vnicName) |
Caused by connectivity issues with the EFLOW virtual machine. The errors are generally related to an IP address change (if using static IP) or failure to assign an IP if using DHCP server. | Make sure to use the appropriate networking configuration. If there's a valid DHCP server, you can use DHCP assignation. If using static IP, make sure the IP configuration is correct (all three parameters: ip4Address, ip4GatewayAddress and ip4PrefixLength) and the address isn't being used by another device in the network. For more information about networking configurations, see Azure IoT Edge for Linux on Windows networking. |
| No adapters associated with the switch '$vnetName' are found. No adapters associated with the device ID '$adapterGuid' are found No adapters associated with the adapter name '$name' are found. Network '$vswitchName' does not exist |
Caused by a network communication error between the Windows host OS and the EFLOW virtual machine. | Ensure you can reach the EFLOW VM and establish an SSH channel. Use the Connect-EflowVm PowerShell cmdlet to connect to the virtual machine. If connectivity fails, reboot the EFLOW VM and check again. |
| ip4Address & ip4PrefixLength are required for StaticIP! | During EFLOW VM deployment or when adding multiple NICs, if using static IP, the three static ip parameters are needed: ip4Address, ip4GatewayAddress, ip4PrefixLength. | For more information about Deploy-EFlow PowerShell cmdlet, see PowerShell functions for IoT Edge for Linux on Windows. |
| Found multiple VMMS switches with name '$switchName' of type '$switchType' |
There are two or more virtual switches with the same name and type. This environment conflicts with the EFLOW VM installation and lifecycle of the VM. | Use Get-VmSwitch PowerShell cmdlet to check the virtual switches available in the Windows host and make sure that each {name,type} is unique. |
Next steps
Do you think that you found a bug in the IoT Edge for Linux on Windows? Submit an issue so that we can continue to improve.
If you have more questions, create a Support request for help.