Identify and diagnose issues

Windows Virtual Desktop offers a diagnostics feature that allows the administrator to identify issues through a single interface. The Windows Virtual Desktop roles log a diagnostic activity whenever a user interacts with the system. Each log contains relevant information such as the Windows Virtual Desktop roles involved in the transaction, error messages, tenant information, and user information. Diagnostic activities are created by both end-user and administrative actions, and can be categorized into three main buckets:

  • Feed subscription activities: the end-user triggers these activities whenever they try to connect to their feed through Microsoft Remote Desktop applications.
  • Connection activities: the end-user triggers these activities whenever they try to connect to a desktop or RemoteApp through Microsoft Remote Desktop applications.
  • Management activities: the administrator triggers these activities whenever they perform management operations on the system, such as creating host pools, assigning users to app groups, and creating role assignments.

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.

To get started, download and import the Windows Virtual Desktop PowerShell module to use in your PowerShell session if you haven't already. After that, run the following cmdlet to sign in to your account:

Add-RdsAccount -DeploymentUrl "https://rdbroker.wvd.microsoft.com"

Diagnose issues with PowerShell

Windows Virtual Desktop Diagnostics uses just one PowerShell cmdlet but contains many optional parameters to help narrow down and isolate issues. The following sections list the cmdlets you can run to diagnose issues. Most filters can be applied together. Values listed in brackets, such as <tenantName>, should be replaced with the values that apply to your situation.

Retrieve diagnostic activities in your tenant

You can retrieve diagnostic activities by entering the Get-RdsDiagnosticActivities cmdlet. The following example cmdlet will return a list of diagnostic activities, sorted from most to least recent.

Get-RdsDiagnosticActivities -TenantName <tenantName>

Like other Windows Virtual Desktop PowerShell cmdlets, you must use the -TenantName parameter to specify the name of the tenant you want to use for your query. The tenant name is applicable for almost all diagnostic activity queries.

Retrieve detailed diagnostic activities

The -Detailed parameter provides additional details for each diagnostic activity returned. The format for each activity varies depending on its activity type. The -Detailed parameter can be added to any Get-RdsDiagnosticActivities query, as shown in the following example.

Get-RdsDiagnosticActivities -TenantName <tenantName> -Detailed

Retrieve a specific diagnostic activity by activity ID

The -ActivityId parameter returns a specific diagnostic activity if it exists, as shown in the following example cmdlet.

Get-RdsDiagnosticActivities -TenantName <tenantName> -ActivityId <ActivityIdGuid>

View error messages for a failed activity by activity ID

To view the error messages for a failed activity, you must run the cmdlet with the -Detailed parameter. You can view the list of errors by running the Select-Object cmdlet.

Get-RdsDiagnosticActivities -TenantName <tenantname> -ActivityId <ActivityGuid> -Detailed | Select-Object -ExpandProperty Errors

Filter diagnostic activities by user

The -UserName parameter returns a list of diagnostic activities initiated by the specified user, as shown in the following example cmdlet.

Get-RdsDiagnosticActivities -TenantName <tenantName> -UserName <UserUPN>

The -UserName parameter can also be combined with other optional filtering parameters.

Filter diagnostic activities by time

You can filter the returned diagnostic activity list with the -StartTime and -EndTime parameters. The -StartTime parameter will return a diagnostic activity list starting from a specific date, as shown in the following example.

Get-RdsDiagnosticActivities -TenantName <tenantName> -StartTime "08/01/2018"

The -EndTime parameter can be added to a cmdlet with the -StartTime parameter to specify a specific period of time you want to receive results for. The following example cmdlet will return a list of diagnostic activities from between August 1 and August 10.

Get-RdsDiagnosticActivities -TenantName <tenantName> -StartTime "08/01/2018" -EndTime "08/10/2018"

The -StartTime and -EndTime parameters can also be combined with other optional filtering parameters.

Filter diagnostic activities by activity type

You can also filter diagnostic activities by activity type with the -ActivityType parameter. The following cmdlet will return a list of end-user connections:

Get-RdsDiagnosticActivities -TenantName <tenantName> -ActivityType Connection

The following cmdlet will return a list of administrator management tasks:

Get-RdsDiagnosticActivities -TenantName <tenantName> -ActivityType Management

The Get-RdsDiagnosticActivities cmdlet doesn’t currently support specifying Feed as the ActivityType.

Filter diagnostic activities by outcome

You can filter the returned diagnostic activity list by outcome with the -Outcome parameter. The following example cmdlet will return a list of successful diagnostic activities.

Get-RdsDiagnosticActivities -TenantName <tenantName> -Outcome Success

The following example cmdlet will return a list of failed diagnostic activities.

Get-RdsDiagnosticActivities -TenantName <tenantName> -Outcome Failure

The -Outcome parameter can also be combined with other optional filtering parameters.

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 tenant administrator and need to be resolved as a support issue. When providing feedback through the Windows Virtual Desktop Tech Community, include the activity ID and approximate time frame of when the issue occurred.
  • External Issue: relate to scenarios which can be mitigated by the system administrator. These are external to Windows Virtual Desktop.

The following table lists common errors your admins might run into.

Note

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.

External management error codes

Numeric code Error code Suggested solution
3 UnauthorizedAccess The user who tried to run the administrative PowerShell cmdlet either doesn't have permissions to do so or mistyped their username.
1000 TenantNotFound The tenant name you entered doesn't match any existing tenants. Review the tenant name for typos and try again.
1006 TenantCannotBeRemovedHasSessionHostPools You can't delete a tenant as long it contains objects. Delete the session host pools first, then try again.
2000 HostPoolNotFound The host pool name you entered doesn't match any existing host pools. Review the host pool name for typos and try again.
2005 HostPoolCannotBeRemovedHasApplicationGroups You can't delete a host pool as long as it contains objects. Remove all app groups in the host pool first.
2004 HostPoolCannotBeRemovedHasSessionHosts Remove all sessions hosts first before deleting the session host pool.
5001 SessionHostNotFound The session host you queried might be offline. Check the host pool's status.
5008 SessionHostUserSessionsExist You must sign out all users on the session host before executing your intended management activity.
6000 AppGroupNotFound The app group name you entered doesn't match any existing app groups. Review the app group name for typos and try again.
6022 RemoteAppNotFound The RemoteApp name you entered doesn't match any RemoteApps. Review RemoteApp name for typos and try again.
6010 PublishedItemsExist The name of the resource you're trying to publish is the same as a resource that already exists. Change the resource name and try again.
7002 NameNotValidWhiteSpace Don’t use white space in the name.
8000 InvalidAuthorizationRoleScope The role name you entered doesn't match any existing role names. Review the role name for typos and try again.
8001 UserNotFound The user name you entered doesn't match any existing user names. Review the name for typos and try again.
8005 UserNotFoundInAAD The user name you entered doesn't match any existing user names. Review the name for typos and try again.
8008 TenantConsentRequired Follow the instructions here to provide consent for your tenant.

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.
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.

Next steps

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.