Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Troubleshoot WorkSpaces issues

The following information can help you troubleshoot issues with your WorkSpaces.

Enabling advanced logging

To help troubleshoot issues that your users might experience, you can enable advanced logging on any Amazon WorkSpaces client.

Advanced logging generates log files that contain diagnostic information and debugging-level details, including verbose performance data. For the 1.0+ and 2.0+ clients, these advanced logging files are automatically uploaded to a database in Amazon.

Troubleshoot specific issues

The following information can help you troubleshoot specific issues with your WorkSpaces.

I can't create an Amazon Linux WorkSpace because there are non-valid characters in the user name

For Amazon Linux WorkSpaces, user names:

I changed the shell for my Amazon Linux WorkSpace and now I can't provision a PCoIP session

To override the default shell for Linux WorkSpaces, see Override the default shell for Amazon Linux WorkSpaces.

My Amazon Linux WorkSpaces won't start

Starting July 20, 2020, Amazon Linux WorkSpaces will be using new license certificates. These new certificates are compatible only with versions 2.14.1.1, 2.14.7, 2.14.9, and 20.10.6 or later of the PCoIP agent.

If you're using an unsupported version of the PCoIP agent, you must upgrade it to the latest version (20.10.6), which has the latest fixes and performance improvements that are compatible with the new certificates. If you don't make these upgrades by July 20, session provisioning for your Linux WorkSpaces will fail and your end users won't be able to connect to their WorkSpaces.

If your Linux WorkSpace still fails to start after you upgrade the PCoIP agent, contact Amazon Support.

Launching WorkSpaces in my connected directory often fails

Verify that the two DNS servers or domain controllers in your on-premises directory are accessible from each of the subnets that you specified when you connected to your directory. You can verify this connectivity by launching an Amazon EC2 instance in each subnet and joining the instance to your directory using the IP addresses of the two DNS servers.

Launching WorkSpaces fails with an internal error

Check whether your subnets are configured to automatically assign IPv6 addresses to instances launched in the subnet. To check this setting, open the Amazon VPC console, select your subnet, and choose Subnet Actions, Modify auto-assign IP settings. If this setting is enabled, you cannot launch WorkSpaces using the Performance or Graphics bundles. Instead, disable this setting and specify IPv6 addresses manually when you launch your instances.

When I try to register a directory, the registration fails and leaves the directory in an ERROR state

This problem can occur if you're trying to register an Amazon Managed Microsoft AD directory that has been configured for multi-Region replication. Although the directory in the primary Region can be successfully registered for use with Amazon WorkSpaces, attempting to register the directory in a replicated Region fails. Multi-Region replication with Amazon Managed Microsoft AD isn't supported for use with Amazon WorkSpaces within replicated Regions.

My users can't connect to a Windows WorkSpace with an interactive logon banner

If an interactive logon message has been implemented to display a logon banner, this prevents users from being able to access their Windows WorkSpaces. The interactive logon message Group Policy setting is not currently supported by WorkSpaces. Move the WorkSpaces to an organizational unit (OU) where the Interactive logon: Message text for users attempting to log on Group Policy isn’t applied.

My users can't connect to a Windows WorkSpace

My users receive the following error when they try to connect to their Windows WorkSpaces:

"An error occurred while launching your WorkSpace. Please try again."

This error often occurs when the WorkSpace can't load the Windows desktop using PCoIP. Check the following:

Another cause of this error is related to the User Rights Assignment Group Policy. If the following group policy is incorrectly configured, it prevents users from being able to access their Windows WorkSpaces:

Computer Configuration\Windows Settings\Security Settings\Local Policies\User Rights Assignment

For more information, see Access this computer from the network - security policy setting and Configure security policy settings in the Microsoft Windows documentation.

The Amazon WorkSpaces client displays a gray "Loading..." screen for a while before returning to the login screen. No other error message appears.

This behavior usually indicates that the WorkSpaces client can authenticate over port 443, but can't establish a streaming connection over port 4172 (PCoIP) or port 4195 (WSP). This situation can occur when network prerequisites aren't met. Issues on the client side often cause the network check in the client to fail. To see which health checks are failing, choose the network check icon (typically a red triangle with an exclamation point in the bottom-right corner of the login screen for 2.0+ clients or the network icon in the upper-right corner of the 3.0+ clients).

If the network check passes, there might be a problem with the network configuration of the WorkSpace. For example, a Windows Firewall rule might block port UDP 4172 or 4195 on the management interface. Connect to the WorkSpace using a Remote Desktop Protocol (RDP) client to verify that the WorkSpace meets the necessary port requirements.

My users receive the message "WorkSpace Status: Unhealthy. We were unable to connect you to your WorkSpace. Please try again in a few minutes."

This error usually indicates the SkyLightWorkSpacesConfigService service isn't responding to health checks.

If you just rebooted or started your WorkSpace, wait a few minutes, and then try again.

If the WorkSpace has been running for some time and you still see this error, connect using RDP to verify that the SkyLightWorkSpacesConfigService service:

My users receive the message "This device is not authorized to access the WorkSpace. Please contact your administrator for assistance."

This error indicates that IP access control groups are configured on the WorkSpace directory, but the client IP address isn't allowlisted.

Check the settings on your directory. Confirm that the public IP address the user is connecting from allows access to the WorkSpace.

My users receive the message "No network. Network connection lost. Check your network connection or contact your administrator for help." when trying to connect to a WSP WorkSpace

If this error occurs and your users don't have connectivity issues, make sure that port 4195 is open on your network's firewalls. For WorkSpaces using the WorkSpaces Streaming Protocol (WSP), the port used to stream the client session was changed from 4172 to 4195.

The WorkSpaces client gives my users a network error, but they are able to use other network-enabled apps on their devices

The WorkSpaces client applications rely on access to resources in the Amazon Cloud, and require a connection that provides at least 1 Mbps download bandwidth. If a device has an intermittent connection to the network, the WorkSpaces client application might report an issue with the network.

WorkSpaces enforces the use of digital certificates issued by Amazon Trust Services, as of May 2018. Amazon Trust Services is already a trusted Root CA on the operating systems that are supported by WorkSpaces. If the Root CA list for the operating system is not up to date, the device cannot connect to WorkSpaces and the client gives a network error.

Windows client application

Use one of the following solutions for certificate failures.

Solution 1: Update the client application

Download and install the latest Windows client application from https://clients.amazonworkspaces.awsapps.cn/. During installation, the client application ensures that your operating system trusts certificates issued by Amazon Trust Services.

Solution 3: Deploy Amazon Trust Services as a trusted CA using Group Policy

Add the Starfield certificate to the trusted Root CAs for the domain using Group Policy. For more information, see Use Policy to Distribute Certificates.

PCoIP zero clients

To connect directly to a WorkSpace using firmware version 6.0 or later, download and install the certificate issued by Amazon Trust Services.

Other client applications

Add the Starfield certificate (2b071c59a0a0ae76b0eadb2bad23bad4580b69c3601b630c2eaf0613afa83f92) from Amazon Trust Services. For more information about how to add a Root CA, see the following documentation:

My WorkSpace users see the following error message: "Device can't connect to the registration service. Check your network settings."

When a registration service failure occurs, your WorkSpace users might see the following error message on the Connection Health Check page: "Your device is not able to connect to the WorkSpaces Registration service. You will not be able to register your device with WorkSpaces. Please check your network settings."

This error occurs when the WorkSpaces client application can't reach the registration service. Typically, this happens when the WorkSpaces directory has been deleted. To resolve this error, make sure that the registration code is valid and corresponds to a running directory in the Amazon Cloud.

My PCoIP zero client users are receiving the error "The supplied certificate is invalid due to timestamp"

If Network Time Protocol (NTP) isn't enabled in Teradici, your PCoIP zero client users might receive certificate failure errors. To set up NTP, see Set up PCoIP zero clients for WorkSpaces.

USB printers and other USB peripherals aren't working for PCoIP zero clients

Starting with version 20.10.4 of the PCoIP agent, Amazon WorkSpaces disables USB redirection by default through the Windows registry. This registry setting affects the behavior of USB peripherals when your users are using PCoIP zero client devices to connect to their WorkSpaces.

If your WorkSpaces are using version 20.10.4 or later of the PCoIP agent, USB peripheral devices won't work with PCoIP zero client devices until you've enabled USB redirection.

My users skipped updating their Windows or macOS client applications and aren't getting prompted to install the latest version

When users skip updates to the Amazon WorkSpaces Windows client application, the SkipThisVersion registry key gets set, and they are no longer prompted to update their clients when a new version of the client is released. To update to the latest version, you can edit the registry as described in Update the WorkSpaces Windows Client Application to a Newer Version in the Amazon WorkSpaces User Guide. You can also run the following PowerShell command:

Remove-ItemProperty -Path "HKCU:\Software\Amazon Web Services. LLC\Amazon WorkSpaces\WinSparkle" -Name "SkipThisVersion"

When users skip updates to the Amazon WorkSpaces macOS client application, the SUSkippedVersion preference gets set, and they are no longer prompted to update their clients when a new version of the client is released. To update to the latest version, you can reset this preference as described in Update the WorkSpaces macOS Client Application to a Newer Version in the Amazon WorkSpaces User Guide.

My users aren't receiving invitation emails or password reset emails

Users do not automatically receive welcome or password reset emails for WorkSpaces that were created using AD Connector or a trusted domain. Invitation emails also aren't sent automatically if the user already exists in Active Directory.

To manually send welcome emails to these users, see Send an invitation email.

To reset user passwords, see Set up Active Directory Administration Tools for WorkSpaces.

My users don't see the Forgot password? option on the client login screen

If you're using AD Connector or a trusted domain, your users won't be able to reset their own passwords. (The Forgot password? option on the WorkSpaces client application login screen won't be available.) For information about how to reset user passwords, see Set up Active Directory Administration Tools for WorkSpaces.

I receive the message "The system administrator has set policies to prevent this installation" when I try to install applications on a Windows WorkSpace

You can address this issue by modifying the Windows Installer Group Policy setting. To deploy this policy to multiple WorkSpaces in your directory, apply this setting to a Group Policy object that is linked to the WorkSpaces organizational unit (OU) from a domain-joined EC2 instance. If you are using AD Connector, you can make these changes from a domain controller. For more information about using the Active Directory administration tools to work with Group Policy objects, see Installing the Active Directory Administration Tools in the Amazon Directory Service Administration Guide.

The following procedure shows how to configure the Windows Installer setting for the WorkSpaces Group Policy object.

No WorkSpaces in my directory can connect to the internet

WorkSpaces cannot communicate with the internet by default. You must explicitly provide internet access. For more information, see Provide internet access from your WorkSpace.

My WorkSpace has lost its internet access

If your WorkSpace has lost access to the internet and you can't connect to the WorkSpace by using RDP, this issue is probably caused by the loss of the public IP address for the WorkSpace. If you have enabled automatic assignment of Elastic IP addresses at the directory level, an Elastic IP address (from the Amazon-provided pool) is assigned to your WorkSpace when it is launched. However, if you associate an Elastic IP address that you own to a WorkSpace, and then you later disassociate that Elastic IP address from the WorkSpace, the WorkSpace loses its public IP address, and it doesn't automatically get a new one from the Amazon-provided pool.

To associate a new public IP address from the Amazon-provided pool with the WorkSpace, you must rebuild the WorkSpace. If you don't want to rebuild the WorkSpace, you must associate another Elastic IP address that you own to the WorkSpace.

We recommend that you not modify the elastic network interface of a WorkSpace after the WorkSpace is launched. After an Elastic IP address has been assigned to a WorkSpace, the WorkSpace retains the same public IP address (unless the WorkSpace is rebuilt, in which case it gets a new public IP address).

I receive a "DNS unavailable" error when I try to connect to my on-premises directory

You receive an error message similar to the following when connecting to your on-premises directory.

DNS unavailable (TCP port 53) for IP: dns-ip-address

AD Connector must be able to communicate with your on-premises DNS servers via TCP and UDP over port 53. Verify that your security groups and on-premises firewalls allow TCP and UDP communication over this port.

I receive a "Connectivity issues detected" error when I try to connect to my on-premises directory

You receive an error message similar to the following when connecting to your on-premises directory.

Connectivity issues detected: LDAP unavailable (TCP port 389) for IP: ip-address
Kerberos/authentication unavailable (TCP port 88) for IP: ip-address
Please ensure that the listed ports are available and retry the operation.

AD Connector must be able to communicate with your on-premises domain controllers via TCP and UDP over the following ports. Verify that your security groups and on-premises firewalls allow TCP and UDP communication over these ports:

I receive an "SRV record" error when I try to connect to my on-premises directory

You receive an error message similar to one or more of the following when connecting to your on-premises directory.

SRV record for LDAP does not exist for IP: dns-ip-address

SRV record for Kerberos does not exist for IP: dns-ip-address

AD Connector needs to obtain the _ldap._tcp.dns-domain-name and _kerberos._tcp.dns-domain-name SRV records when connecting to your directory. You get this error if the service cannot obtain these records from the DNS servers that you specified when connecting to your directory. Make sure that your DNS servers contain these SRV records. For more information, see SRV Resource Records on Microsoft TechNet.

My Windows WorkSpace goes to sleep when it's left idle

To resolve this issue, connect to the WorkSpace and change the power plan to High performance by using the following procedure:

If the preceding steps do not solve the issue, do the following:

One of my WorkSpaces has a state of UNHEALTHY

The WorkSpaces service periodically sends status requests to a WorkSpace. A WorkSpace is marked UNHEALTHY when it fails to respond to these requests. Common causes for this problem are:

You can attempt to correct the situation using the following methods:

My WorkSpace is unexpectedly crashing or rebooting

If your WorkSpace configured for PCoIP is repeatedly crashing or rebooting and your error logs or crash dumps are pointing to problems with spacedeskHookKmode.sys or spacedeskHookUmode.dll, or if you're receiving the following error messages, you might need to disable Web Access to the WorkSpace:

The kernel power manager has initiated a shutdown transition.
Shutdown reason: Kernel API

The computer has rebooted from a bugcheck.

To disable Web Access to the WorkSpace, you must disable Web Access in the WorkSpaces directory and reboot the WorkSpace.

The same username has more than one WorkSpace, but the user can log in to only one of the WorkSpaces

If you delete a user in Active Directory (AD) without first deleting their WorkSpace and then you add the user back to Active Directory and create a new WorkSpace for that user, the same username will now have two WorkSpaces in the same directory. However, if the user tries to connect to their original WorkSpace, they will receive the following error:

"Unrecognized user. No WorkSpace found under your username. Contact your administrator to request one."

Additionally, searches for the username in the Amazon WorkSpaces console return only the new WorkSpace, even though both WorkSpaces still exist. (You can find the original WorkSpace by searching for the WorkSpace ID instead of the username.)

This behavior can also occur if you rename a user in Active Directory without first deleting their WorkSpace. If you then change their username back to the original username and create a new WorkSpace for the user, the same username will have two WorkSpaces in the directory.

This problem occurs because Active Directory uses the user's security identifier (SID), rather than the username, to uniquely identify the user. When a user is deleted and recreated in Active Directory, the user is assigned a new SID, even if their username remains the same. During searches for a username, the Amazon WorkSpaces console uses the SID to search Active Directory for matches. The Amazon WorkSpaces clients also use the SID to identify users when they are connecting to WorkSpaces.

To resolve this problem, do one of the following:

I'm having trouble using Docker with Amazon WorkSpaces

Windows WorkSpaces

Nested virtualization (including the use of Docker) is not supported on Windows WorkSpaces. For more information, see the Docker documentation.

Linux WorkSpaces

To use Docker on Linux WorkSpaces, make sure that the CIDR blocks used by Docker don't overlap with the CIDR blocks used in the two elastic network interfaces (ENIs) associated with the WorkSpace. If you encounter problems with using Docker on Linux WorkSpaces, contact Docker for assistance.

I receive ThrottlingException errors to some of my API calls

The default allowed rate for WorkSpaces API calls is a constant rate of two API calls per second, with a maximum allowed "burst" rate of five API calls per second. The following table shows how the burst rate limit works for API requests.

My WorkSpace keeps disconnecting when I let it run in the background

For Mac users, check to see if the Power Nap feature is on. If it is on, turn it off. To turn Power Nap off, open your terminal and run the following command:

defaults write com.amazon.workspaces NSAppSleepDisabled -bool YES

SAML 2.0 federation isn't working. My users are not authorized to stream their WorkSpaces desktop.

This might happen because the inline policy that is embedded for the SAML 2.0 federation IAM role does not include permissions to stream from the directory Amazon Resource Name (ARN). The IAM role is assumed by the federated user who is accessing a WorkSpaces directory. Edit the role permissions to include the directory ARN and ensure that the user has a WorkSpace in the directory. For more information, see SAML 2.0 Authentication and Troubleshooting SAML 2.0 Federation with Amazon.

My users are getting disconnected from their WorkSpaces session every 60 minutes.

If you have configured SAML 2.0 authentication to WorkSpaces, depending on your identity provider (IdP), you might need to configure the information that the IdP passes as SAML attributes to Amazon as part of the authentication response. This includes configuring the Attribute element with the SessionDuration attribute set to https://aws.amazon.com/SAML/Attributes/SessionDuration.

SessionDuration specifies the maximum amount of time that a federated streaming session can remain active for a user before reauthentication is required. Although SessionDuration is an optional attribute, we recommend that you include it in the SAML authentication response. If you don't specify this attribute, the session duration defaults to 60 minutes.

To resolve this issue, configure your IdP to include the SessionDuration value in the SAML authentication response and set the value as required. For more information, see Step 5: Create assertions for the SAML authentication response.

My users get a redirect URI error when they federate using the SAML 2.0 identity provider (IdP)-initiated flow, or an additional instance of the WorkSpaces client application starts every time my users attempt to sign in from the client after federating to the IdP.

This error occurs due to a relay state URL that's not valid. Make sure that the relay state in your IdP federation setup is correct, and that the user access URL and relay state parameter name are configured correctly for your IdP federation in the WorkSpaces directory properties. If they are valid and the problem still persists, contact Amazon Support. For more information, see Setting Up SAML.

My users receive the message, "Something went wrong: An error occurred while launching your WorkSpace" when they attempt to sign in to the WorkSpaces client application after federating to the IdP.

Review the SAML 2.0 assertions for your federation. The SAML Subject NameID value must match the WorkSpaces user name, and is typically the same as the sAMAccountName attribute for the Active Directory user. In addition, the Attribute element that has the PrincipalTag:Email attribute set to https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email must match the WorkSpaces user's email address as defined in the WorkSpaces directory. For more information, see Setting Up SAML.

My users receive the message, "Unable to validate tags” when they attempt to sign in to the WorkSpaces client application after federating to the IdP.

Review the PrincipalTag attribute values in the SAML 2.0 assertions for your federation, such as https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email. Tag values may include combinations of the characters _ . : / = + - @, letters, numbers, and spaces.. For more information, see Rules for tagging in IAM and Amazon STS.

My users receive the message, "The client and the server cannot communicate, because they do not possess a common algorithm".

This problem can occur if you do not enable TLS 1.2.

My microphone or web cam is not working on Windows WorkSpaces.

Check your privacy setting by opening the Start menu

If they are turned off turn them on.

Alternatively, WorkSpaces administrators can create a Group Policy Object (GPO) to enable microphone and or webcam as needed.

My users cannot log in using certificate-based authentication and are prompted for the password either at the WorkSpaces client or the Windows sign-on screen when they connect to their desktop session.

Certificate-based authentication was unsuccessful for the session. If the problem continues, certificate-based authentication failure can be the result of one of the following issues:

Additional troubleshooting steps involve reviewing the WorkSpaces instance Windows event logs. A common event to review for logon failure is Event 4625: An account failed to logon in the Windows Security log.

If the problem persists, contact Amazon Web Services Support. For more information, see Amazon Web Services Support Center.

I am trying to do something that requires Windows installation media but WorkSpaces does not provide it.

If you are using an Amazon-provided public bundle, you can use the Windows Server OS installation media EBS snapshots provided by Amazon EC2 when needed.

Create an EBS volume from these snapshots, attach it to Amazon EC2, and transfer the files to the WorkSpace where the files as needed. If you are using Windows 10 on BYOL on WorkSpaces and need an installation media, you will need to prepare your own installation media. For more information, see Add Windows components using installation media. Since you can't directly attach an EBS volume to a WorkSpace, you'll need to attach it to an Amazon EC2 instance and copy the files.

I want to launch WorkSpaces with an existing Amazon Managed Directory created in an unsupported WorkSpaces Region.

To launch Amazon WorkSpaces using a directory in a Region that is not currently supported by WorkSpaces, follow the steps below.

Step 1: Create virtual private cloud (VPC) peering with another VPC in your account

Step 2: Update route tables for VPC peering in both Regions

Update your route tables to turn on communication with the peer VPC over IPv4 or IPv6. For more information, see Update your route tables for a VPC peering connection.

Step 3: Create an AD Connector and register Amazon WorkSpaces

I want to update Firefox on Amazon Linux 2.

Step 1: Verify auto-update is enabled

To verify that autoupdate is enabled, run the command systemctl status *os-update-mgmt.timer | grep enabled on your WorkSpace. In the output, there should be two lines with the word enabled on them.

Step 2: Initiate an update

Firefox usually updates automatically in Amazon Linux 2 WorkSpaces along with all other software packages in the system during the maintenance window. However, this depends on the type of WorkSpaces you are using.

For more information about maintenance windows, see WorkSpace maintenance.

You can also initiate an immediate update cycle by rebooting your WorkSpace and reconnecting after 15 minutes. You can also initiate updates by entering sudo yum update. To initiate an update for Firefox only, enter sudo yum install firefox.

If you are not able to configure access for Amazon Linux 2 repositories and prefer to install Firefox using binaries built by Mozilla, see Install Firefox from Mozilla builds on Mozilla support. We recommend uninstalling the RPM-packaged version of Firefox altogether to make sure you don't run an outdated version by mistake. You can uninstall it by running command sudo yum remove firefox.

You can also download the necessary RPM packages from Amazon Linux 2 repositories by running the command yumdownloader firefox on a different machine. Then, side-load the repositories onto WorkSpaces, where you can install them with a standard YUM command like sudo yum install firefox-102.11.0-2.amzn2.0.1.x86_64.rpm.

Step 3: Verify Firefox repository is used

Amazon Linux Extras automatically provides Firefox updates for Amazon Linux 2 WorkSpaces. Amazon Linux 2 WorkSpaces created after July 31, 2023 will already have the Firefox Extra repository activated. To verify that your WorkSpace is using the Firefox Extra repository, run the following command.

yum repolist | grep amzn2extra-firefox

The command output should look something like amzn2extra-firefox/2/x86_64 Amazon Extras repo for firefox 10 if Firefox Extra repository is used. It will be empty if the Firefox Extra repository is not used. If Firefox Extra repository is not used, you can attempt to enable it manually with the following command:

sudo amazon-linux-extras install firefox

If the Firefox Extra repository activation still fails, check your internet access and ensure that your VPC endpoints are unconfigured. To continue receiving Firefox updates for Amazon Linux 2 WorkSpaces via YUM repositories, ensure that your WorkSpaces are able to reach Amazon Linux 2 repositories. For more information on accessing Amazon Linux 2 repositories without internet access, see this knowledge center article.

My user is able to reset their password using the WorkSpaces client, ignoring the Fine Grained Password Policy (FFGP) setting that is configured on Amazon Managed Microsoft AD.

If your user's WorkSpaces client is associated with Amazon Managed Microsoft AD, they will have to reset their password using the default complexity setting.

The default complexity password is case-sensitive and must be between 8 and 64 characters in length, inclusive. It must contain at least one character from each of the following categories:

Make sure the password doesn't include non-printable unicode characters, such as white spaces, carriage reture tabs, line breaks, and null characters.

If your organization requires you to enforce FFGP for WorkSpaces, contact your Active Directory administrator to reset your user's password directly from the Active Directory instead of the WorkSpaces client.