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

Resolution

You modified or configured the user data, but it doesn't run on instance launch. Or, you can't configure the user data

When you work with user data, follow these criteria:

• You must Base64 encode user data.
• Before it's base64 encoded, user data is limited to 16 KB in raw form.
• You must Base64 decode user data when you retrieve it. 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 then modify its user data, then the updated user data doesn't run when you start the instance.
• User data scripts require a specific syntax. For more information and examples of script syntax, see User data scripts.
• Run the scripts in a local test environment to validate the syntax.
• The EC2 instance must connect to the metadata service 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. For more information, see Why does my Amazon EC2 Windows instance generate a "Waiting for the metadata service" error?

By default, 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 the 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 v2: C:\ProgramData\Amazon\EC2Launch\log\agent.log
• EC2Launch: C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log
• EC2Config: C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2ConfigLog.txt

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