How can I troubleshoot running user data scripts to configure my EC2 Windows instance?

Short description

When launching an EC2 Windows instance, you can pass user data to the instance that can be used to perform automated configuration tasks. Or, you can pass user data to run scripts after the instance starts.

The following are common issues that occur when utilizing Windows EC2 instance user data:

• You modified or configured user data, but it doesn't run on instance launch.
• You can't configure user data.
• User data doesn't run on subsequent reboots or starts.
• You can't find the user data logs.

Resolution

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

Keep the following in mind when working with user data:

• User data must be Base64-encoded.
• User data is limited to 16 KB, in raw form, before it is Base64-encoded.
• User data must be Base64-decoded when retrieved. If you retrieve the data using 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, the updated user data isn'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.

User data doesn't run on subsequent 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 v2, EC2Launch, 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

Related information

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