How do I troubleshoot a Windows WorkSpace that's in the Unhealthy state?

Short description

WorkSpaces periodically sends a health status request to each WorkSpace to check the health of the WorkSpace. If WorkSpaces doesn't receive a response from the WorkSpace, then the WorkSpace status changes to Unhealthy.

The following issues can cause the status to change to Unhealthy:

• The WorkSpace has consistently high CPU utilization.
• The agent or service that responds to WorkSpaces isn't running, or the management interface (ETH0) is turned off.
• An Amazon DCV or PCoIP service isn't running.
• Antivirus software is blocking WorkSpaces components.
• An application or Group Policy on the WorkSpace is blocking the network connection between WorkSpaces and the WorkSpace on the management interface.
• Metadata routes are missing.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Use CloudWatch metrics to review your WorkSpaces

To help you determine the cause, review the CPUUsage, MemoryUsage, and Unhealthy WorkSpaces metrics in Amazon CloudWatch.

Reboot the WorkSpace

Reboot the WorkSpace. If a reboot doesn't resolve the issue, then use Remote Desktop Protocol (RDP) to connect to the WorkSpace.

If you can't use RDP to connect to the WorkSpace, then see How do I troubleshoot RDP connection issues with my Amazon Elastic Compute Cloud (Amazon EC2) Windows instance? If you still can't connect to the WorkSpace with RDP, then see the Restore or rebuild the WorkSpace section.

You can also run the reboot-workspaces AWS CLI command.

Check for high CPU utilization

Check your Amazon EC2 instance for high CPU utilization.

Check that the management and customer interfaces are running

To identify the management and customer interface IP addresses, run the following command:

ipconfig /all

To show the state of the management and customer interfaces, run the following command:

netsh interface show interface

If an interface isn't in the Connected state, then run the following command to activate the interface:

netsh interface set interface "interface-name" enable

Note: Replace interface-name with your interface name.

Confirm that the WorkSpaces services are running and responsive

 To check the service's status, complete the following steps:

1. Use RDP to connect to the WorkSpace.
2. Choose the Start menu, and then enter Services.
3. Choose the Services tab.
4. Check each service's status for your WorkSpace:
   PCoIP WorkSpace:
   SkylightWorkSpacesConfigService
   PCoIP Standard Agent for Windows
   DCV WorkSpace:
   SkylightWorkSpacesConfigService
   WSP Adapter for DC
   DCV Server
5. If a service isn't in the Running state, then open the context menu and select the service. 
   Note: Make sure that Start type is set to Automatic for the service.
6. Choose Start.

Verify your WorkSpaces configuration

Verify that endpoint protection software, such as antivirus or anti-malware software, allows the WorkSpaces service components. If you turned on WorkSpaces Web Access for PCoIP WorkSpaces, then verify that the STXHD Hosted Application Service is Running and Start type is Automatic.

Note: If you're not using WorkSpaces Web Access, then turn off the STXHD agent.

Also, verify that an application or VPN isn't blocking your management adapter. Then, check your WorkSpace connectivity.

To check whether the Skylight certificate is in your certificate store, open certmgr.msc on your local computer. The certificate is in the Skylight folder.

To verify whether a Group Policy is blocking the communication on the management interface or a required WorkSpaces service, complete the following steps:

1. Use RDP to connect to the WorkSpace.

2. Launch Command Prompt, and then run the following command to create a policy.html file:

   gpresult /h policy.html

3. Open the policy.html document, and then search for policies that block communication to network interfaces or WorkSpaces services.

4. If you identify a blocking policy, then move the WorkSpace computer object to a separate organizational unit (OU) in Microsoft Active Directory. Use the Block inheritance setting for the object. For more information about how to use Block inheritance, see Overriding and blocking Group Policy on the Microsoft website.

5. Reboot the WorkSpace.

Verify firewall rules

The firewall must allow listed traffic on the management network interface. Also, verify that the operating system (OS) firewall or a third-party firewall has rules that allow the required ports.

Check whether the metadata routes are missing

To check whether all required metadata routes are in your WorkSpace, run the following Windows PowerShell command:

Get-NetRoute

If a metadata route is missing, then run the following script to add it to your WorkSpace:

$mgmtIp = (Get-ItemProperty "hklm:\software\Amazon\SkyLight\ConfigurationData").ManagementIp
$mgmtGW = (Get-WmiObject win32_networkAdapterConfiguration | where IPAddress -eq $mgmtIp |select DefaultIPGateway).DefaultIPGateway

if($mgmtGW){

route delete 169.254.169.123
route delete 169.254.169.249
route delete 169.254.169.250
route delete 169.254.169.251
route delete 169.254.169.252
route delete 169.254.169.253
route delete 169.254.169.254

route -P add 169.254.169.249 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.250 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.251 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.252 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.253 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.254 MASK 255.255.255.255 $mgmtGW METRIC 1000
route -P add 169.254.169.123 MASK 255.255.255.255 $mgmtGW METRIC 1000

}

After you add the missing metadata route, reboot the WorkSpace.

Restore or rebuild the WorkSpace

If you can't use RDP to connect to the WorkSpace, then restore the WorkSpace to roll back to the latest snapshot. If the WorkSpace is still unhealthy, then rebuild the WorkSpace.

To restore or rebuild the WorkSpace, it's a best practice to use the AWS Systems Manager AWSSupport-RecoverWorkSpace runbook.

Important: When you restore or rebuild a WorkSpace, data loss can occur. The restoration restores the WorkSpace from the last available snapshot that's up to 12 hours old. The rebuild recreates the user volume from the most recent snapshot and the WorkSpace from the image of the bundle that you created the WorkSpace from. You lose applications that you installed or system settings that you changed after you created the WorkSpace.

Before you run the automation, make sure that your AWS Identity and Access Management (IAM) user or role has the required permissions. For more information, see the Required IAM permissions section of AWSSupport-RecoverWorkSpace.

To run the runbook, complete the following steps:

1. Open the AWSSupport-RecoverWorkSpace runbook.
2. Choose Execute automation.
3. For the input parameters, enter the following values:
   (Optional) For AutomationAssumeRole, enter the Amazon Resource Name (ARN) of the IAM role that allows the automation to perform actions. If you don't specify a role, then the automation uses the permissions of the user that starts the runbook.
   For Acknowledge, enter Yes to acknowledge that the Restore and Rebuild actions recover the WorkSpace from the most recent snapshot.
   For Reboot, Rebuild, or Restore, choose Yes for your preferred option.
   For WorkspaceId, enter the ID of the WorkSpace that you're recovering.
4. Choose Execute.
5. Check the status of your Workspace in the Output section of the runbook.

You can also run the restore-workspace or rebuild-workspaces AWS CLI commands.

If none of the preceding troubleshooting steps resolve your issue, then collect the client-side logs and open an AWS Support case.

Related information

IP address and port requirements for WorkSpaces Personal

Enable self-service WorkSpaces management capabilities for your users in WorkSpaces Personal

How do I troubleshoot a Linux WorkSpace that's in the Unhealthy state?