How can I troubleshoot an AppStream 2.0 image builder that is stuck in Pending status?
Last updated: 2020-09-18
When I try to launch an Amazon AppStream 2.0 image builder, the status stays in Pending state and doesn’t change to Running. How do I fix this?
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.
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, consult the following common causes and troubleshooting steps.
Elastic network interface is deleted or detached
A missing network interface can prevent the image builder from completing the startup 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, 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.
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 isn’t 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 Amazon Web Services (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 getting stuck on the welcome screen.
To fix this issue, launch a new image builder from a recent custom image, or using one of the Amazon-provided base images.
IPv6 is disabled
If you create an image with IPv6 disabled, the image builder will stay 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.
Base image compatibility
Verify that you aren’t launching a new Graphics Pro (NVIDIA) image builder using a Graphics Design (AMD) base image, or vice versa. For more information, see AppStream 2.0 base image version history.
Confirm that there aren’t any installed applications 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) be 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\*
The above 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 disabled, 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, 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 invalid. 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, the image builder instance will be available soon.
If the computer object isn't created, 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 username and password
- Organizational unit (OU) distinguished name