How can I troubleshoot an AppStream 2.0 image builder that is stuck in Pending status?
Last updated: 2023-02-02
When I try to launch an Amazon AppStream 2.0 image builder, the status stays in Pending state and doesn’t change to Running.
It can take up to 25 minutes for image builders and fleet instances to become available and change to a Running state. If your image builder is still in Pending state after 25 minutes, then consult the following common causes and troubleshooting steps.
Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent version of the AWS CLI.
Elastic network interface is deleted or detached
A missing network interface can prevent the image builder from completing the start-up workflows, leaving the status stuck in Pending state.
To verify the state of your network interface, open the Amazon Elastic Compute Cloud (Amazon EC2) console, and then choose Network Interfaces. Or, to use the AWS CLI, enter the following command:
aws ec2 describe-network-interfaces --filters 'Name=description,Values="AppStream 2.0 - image-builder:*"'
If the network interface is missing or detached, then launch a new image builder from the last working image. Or, use a base image provided by AWS.
Note: You can check your AWS CloudTrail logs for event details associated with the network interface deletion or detachment, including eventTime and userIdentity.
PowerShell policy restrictions
Another cause for an image builder to be stuck in a Pending state is having an overly restrictive PowerShell execution policy. Setting the policy to Restricted before image creation causes the image builder to be stuck in a Pending state. Also, other AS2 resources will fail to start when it is next launched. This is due to the Restricted policy preventing any scripts, such as SSM, Sysprep, or reg key setting, from running. You can use either AllSigned or RemoteSigned policies instead to avoid this issue.
Applications using AppX packages
Applications that use AppX packages such as Adobe Creative Cloud can cause Sysprep to fail and image builders to get stuck in Pending state.
Run the following commands in PowerShell as administrator before you complete the last step in the image creation process.
To get a list of the AppX packages on the machine, enter the following command:
Get-AppxPackage | select Name, PackageFullName
To remove a specific AppX package, enter the following command. Replace AppXpackageName with the package that you're removing, as listed in the previous command's output:
Get-AppxPackage -AllUsers -Name AppXpackageName | Remove-AppxPackage -AllUsers
Note: The image builder must run Server 2019. The -AllUsers parameter was added in build 1709. Server 2016 in the image builder runs on build 1607 and returns an error with the -AllUsers parameter.
For more information, see Get-AppxPackage on the Microsoft website.
Device drivers are conflicting or incorrect
The image builder comes pre-installed with all required drivers. The image builder might stay in Pending status if a user installs conflicting or incorrect drivers.
Because the image builder is unreachable, it's not possible to uninstall the conflicting or incorrect drivers. To fix this issue, launch a new image builder from a recent custom image, or using one of the Amazon-provided base images.
Network interface limits
Your AWS account might have reached the network interface limits for the Region. For more information about limits and how to request an increase, see Amazon VPC quotas.
Sysprep answer file customization issues
It's a best practice to not customize the Sysprep Unattend answer file. Incorrect customization can interfere with the Windows start-up process by preventing the image builder from booting correctly and becoming stuck on the welcome screen.
To fix this issue, launch a new image builder from a recent custom image, or by using one of the Amazon-provided base images.
IPv6 is turned off
If you create an image with IPv6 turned off, then the image builder stays in Pending status. To fix this issue, launch a new image builder from a recent custom image, or using one of the Amazon-provided base images.
Confirm that there aren’t any installed applications that are using the following ports:
- Inbound TCP on port 8300, to establish the streaming connection.
- Inbound TCP on ports 8000 and 8443, for management of the streaming instance by AppStream 2.0.
For more information, see Management network interface IP address range and ports.
To allow access to the Amazon EC2 metadata service, all streaming instances require that port 80 (HTTP) is open to IP address 169.254.169.254. If a proxy is configured, then the proxy must exclude 169.254.169.254. For more information, see Customer network interface ports.
Antivirus software exceptions
Antivirus software can block the files and ports that the image builder requires. Consider adding exceptions to the following folder paths:
- %PROGRAMFILES%\Internet Explorer\*
These folder paths correspond to the following services:
- PhotonAgentWebServer (listens on port 8443)
- DcvServer (listens on port 8300)
AWS CLI credentials as system environment variables
Setting AWS CLI credentials as system environment variables might prevent AppStream 2.0 from creating the image. For instructions to change system environment variables across your fleet instances, see Change system environment variables.
Default language changed to an unsupported language
You can configure the default Regional settings for your AppStream 2.0 streaming sessions, including the display language. An image builder will be stuck in Pending if you change the default language to an unsupported language. To view the languages that AppStream 2.0 currently supports, see Specify a default display language.
Deleted or renamed local administrator account
AppStream 2.0 doesn't support renaming or deleting the local administrator account. If you rename or delete this account, the image creation fails.
For domain-joined image builders, if the local administrator account is deactivated, deleted, or renamed by Group Policy, then you can update the Group Policy object (GPO).
If the local administrator account isn't updated by GPO, then launch a new image builder from a recent custom image. Or, use one of the Amazon-provided base images.
Notification codes (Domain-joined image builders)
To see notifications, open the AppStream 2.0 console, and then choose Images from the navigation pane. From the Image Builder tab, select your image builder, and then choose the Notifications tab. For more information, see Troubleshooting notification codes.
- DOMAIN_JOIN_ERROR_NO_SUCH_DOMAIN The image builder instance isn’t able to contact the Active Directory domain. This prevents the image builder from completing the startup workflows. To be sure of network connectivity, confirm your VPC, subnet, and security group settings. Verify that the VPC DNS servers are configured correctly under the DHCP option set section of your VPC. Domain name servers are generally set to the IP addresses of the domain controllers or DNS servers responsible for your domain. For more information, see DHCP options sets.
- DOMAIN_JOIN_ERROR_FILE_NOT_FOUND The organizational unit (OU) distinguished name is not valid. AppStream 2.0 computer objects must be placed in an organizational unit, and the distinguished name must start with OU=. For more information, see Finding the organizational unit distinguished name.
Firewall and network configuration (Domain-joined image builders)
Before adding a Directory Config object to your image builder using the AppStream 2.0 console, confirm that the firewall and network configuration are correct. Follow these steps.
1. Open a PowerShell window from your image builder, and then run the following commands:
Test-NetConnection -ComputerName yourdomain.exampleco.com -Port 389 -InformationLevel "Detailed" Test-NetConnection -ComputerName yourdomain.exampleco.com -Port 88 -InformationLevel "Detailed" Test-NetConnection -ComputerName yourdomain.exampleco.com -Port 53 -InformationLevel "Detailed"
2. For the output of each command, verify that TcpTestSucceeded is True. This indicates that you can reach the required ports to join the domain. For more information, see Test-NetConnection on the Microsoft website.
3. From the same PowerShell window, run the Resolve-DnsName command to confirm that you can look up the domain name:
Resolve-DnsName -Name yourdomain.exampleco.com
Or, download and run the Microsoft PortQryUI tool to validate all the required ports.
New computer object not created (Domain-joined image builders)
In Active Directory, verify whether a new computer object was created in the correct organizational units (OUs).
If there is a new object, then the image builder instance will be available soon.
If the computer object isn't created, then the image builder stays in Pending state. To troubleshoot this issue, first confirm that all required service account permissions are granted. Then, verify that the following directory configuration details in your AppStream 2.0 Directory Config object are correct:
- Directory name (the fully qualified domain name of the directory)
- Service account user name and password
- Organizational unit (OU) distinguished name