Identify and diagnose Windows Virtual Desktop issues
This content applies to Windows Virtual Desktop with Azure Resource Manager Windows Virtual Desktop objects. If you're using Windows Virtual Desktop (classic) without Azure Resource Manager objects, see this article.
Windows Virtual Desktop offers a diagnostics feature that allows the administrator to identify issues through a single interface. To learn more about the diagnostic capabilities of Windows Virtual Desktop, see Use Log Analytics for the diagnostics feature.
Connections that don't reach Windows Virtual Desktop won't show up in diagnostics results because the diagnostics role service itself is part of Windows Virtual Desktop. Windows Virtual Desktop connection issues can happen when the end-user is experiencing network connectivity issues.
Common error scenarios
Error scenarios are categorized in internal to the service and external to Windows Virtual Desktop.
- Internal Issue: specifies scenarios that can't be mitigated by the customer and need to be resolved as a support issue. When providing feedback through the Windows Virtual Desktop Tech Community, include the correlation ID and approximate time frame of when the issue occurred.
- External Issue: relate to scenarios that can be mitigated by the customer. These are external to Windows Virtual Desktop.
The following table lists common errors your admins might run into.
This list includes most common errors and is updated on a regular cadence. To ensure you have the most up-to-date information, be sure to check back on this article at least once a month.
|Error message||Suggested solution|
|Failed to create registration key||Registration token couldn't be created. Try creating it again with a shorter expiry time (between 1 hour and 1 month).|
|Failed to delete registration key||Registration token couldn't be deleted. Try deleting it again. If it still doesn't work, use PowerShell to check if the token is still there. If it's there, delete it with PowerShell.|
|Failed to change session host drain mode||Couldn't change drain mode on the VM. Check the VM status. If the VM's unavailable, drain mode can't be changed.|
|Failed to disconnect user sessions||Couldn't disconnect the user from the VM. Check the VM status. If the VM's unavailable, the user session can't be disconnected. If the VM is available, check the user session status to see if it's disconnected.|
|Failed to log off all user(s) within the session host||Could not sign users out of the VM. Check the VM status. If unavailable, users can't be signed out. Check user session status to see if they're already signed out. You can force sign out with PowerShell.|
|Failed to unassign user from application group||Could not unpublish an app group for a user. Check to see if user is available on Azure AD. Check to see if the user is part of a user group that the app group is published to.|
|There was an error retrieving the available locations||Check location of VM used in the create host pool wizard. If image is not available in that location, add image in that location or choose a different VM location.|
External connection error codes
|Numeric code||Error code||Suggested solution|
|-2147467259||ConnectionFailedAdTrustedRelationshipFailure||The session host is not correctly joined to the Active Directory.|
|-2146233088||ConnectionFailedUserHasValidSessionButRdshIsUnhealthy||The connections failed because the session host is unavailable. Check the session host's health.|
|-2146233088||ConnectionFailedClientDisconnect||If you see this error frequently, make sure the user's computer is connected to the network.|
|-2146233088||ConnectionFailedNoHealthyRdshAvailable||The session the host user tried to connect to isn't healthy. Debug the virtual machine.|
|-2146233088||ConnectionFailedUserNotAuthorized||The user doesn't have permission to access the published app or desktop. The error might appear after the admin removed published resources. Ask the user to refresh the feed in the Remote Desktop application.|
|2||FileNotFound||The application the user tried to access is either incorrectly installed or set to an incorrect path.
When publishing new apps while the user has an active session, the user won’t be able to access this app. The session must be shut down and restarted before the user can access the app.
|3||InvalidCredentials||The username or password the user entered doesn't match any existing usernames or passwords. Review the credentials for typos and try again.|
|8||ConnectionBroken||The connection between Client and Gateway or Server dropped. No action needed unless it happens unexpectedly.|
|14||UnexpectedNetworkDisconnect||The connection to the network dropped. Ask the user to connect again.|
|24||ReverseConnectFailed||The host virtual machine has no direct line of sight to RD Gateway. Ensure the Gateway IP address can be resolved.|
Error: Can't add user assignments to an app group
After assigning a user to an app group, the Azure portal displays a warning that says "Session Ending" or "Experiencing Authentication Issues - Extension Microsoft_Azure_WVD." The assignment page then doesn't load, and after that, pages stop loading throughout the Azure portal (for example, Azure Monitor, Log Analytics, Service Health, and so on).
To learn more about roles within Windows Virtual Desktop, see Windows Virtual Desktop environment.
To see a list of available PowerShell cmdlets for Windows Virtual Desktop, see the PowerShell reference.