How can I troubleshoot issues when I run user data scripts to configure my EC2 Windows instance?

Resolution

Your user data doesn't run on instant launch, or you can't configure the user data

When you work with user data, follow these best practices:

• Encode your user data to base64 format.
• When you retrieve your user data, you must use base64 to decode your data. If you retrieve the data with instance metadata or the Amazon EC2 console, then it's automatically decoded for you.
• If you stop an instance and modify your user data, then the updated user data doesn't run when you start the instance. To resolve this issue, see the following Your user data doesn't run when an EC2 instance reboots or starts section.
• User data scripts require a specific syntax. For more information and examples of script syntax, see User data scripts.
• To validate your script syntax, run the scripts in a local test environment.
• To connect to the metadata service, the EC2 instance must connect on 169.254.169.254.
• When you use a custom Windows image that doesn't use Sysprep, persistent routes might point to the parent instance's default gateway. To resolve this issue, see Why does my Amazon EC2 Windows instance get a "Waiting for the metadata service" error?

Your user data doesn't run when an EC2 instance reboots or starts

When an EC2 instance initially boots, user data runs only once by default. You can configure an instance to run user data every time the instance reboots or starts. For more information, see How do I run a command on an existing EC2 Windows instance when I reboot or start the instance?

You can't find user data logs

The log files for EC2Launch, EC2Launch v2, and EC2Config contain the output from the standard output and standard error streams. You can access the log files at the following locations:

• EC2Launch: C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log
• EC2Launch v2: C:\ProgramData\Amazon\EC2Launch\log\agent.log
• EC2Config: C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2Config.log

Note: By default, C:\ProgramData is a hidden folder.

Related information

How do I run a command on a new EC2 Windows instance at launch?

Sysprep (System Preparation) overview on the Microsoft website