Common Causes of UserData Script Failures

Script Errors

• Syntax errors in bash/PowerShell script

• Missing shebang (#!/bin/bash) at script start

• Wrong line endings (Windows CRLF vs Unix LF)

• Script exits early due to set -e with non-zero exit codes

Permissions & Execution

• No execute permissions on script files

• Running as wrong user (scripts run as root by default)

• Missing dependencies or commands not in PATH

• SELinux/AppArmor blocking script execution

Network & Dependencies

• No internet access during boot (security groups, NACLs)

• Package repositories unreachable (yum, apt updates fail)

• DNS resolution issues preventing downloads

• Instance profile missing required IAM permissions

Instance Configuration

• Wrong AMI (script designed for different OS)

• Instance type limitations (some features unavailable on certain types)

• Insufficient disk space for downloads/installations

• Memory constraints causing OOM kills

UserData Format Issues

• Encoding problems (non-UTF8 characters)

• Size limits exceeded (16KB limit for UserData)

• Base64 encoding corruption when passing through APIs

• Special characters not properly escaped

Quick Debugging Steps

bash

Check if cloud-init ran

sudo cat /var/log/cloud-init.log sudo cat /var/log/cloud-init-output.log

Check UserData was received

curl http://169.254.169.254/latest/user-data

Check system logs

sudo journalctl -u cloud-init sudo tail -f /var/log/messages

Most Common Fix

Add logging to your UserData script: bash #!/bin/bash exec > >(tee /var/log/user-data.log|logger -t user-data -s 2>/dev/console) 2>&1 echo "UserData script started"

Your script here

echo "UserData script completed"

This captures all output for debugging failed executions.

Expected Output from Cloud-Init Debug Commands

sudo cat /var/log/cloud-init.log

2024-01-02 09:10:15,123 - util.py[DEBUG]: Cloud-init v. 23.1.2 running 'init' at Tue, 02 Jan 2024 09:10:15 +0000 2024-01-02 09:10:15,456 - stages.py[INFO]: Running module cc_bootcmd (<module 'cloudinit.config.cc_bootcmd'>) 2024-01-02 09:10:16,789 - handlers.py[DEBUG]: finish: init-network/config-users-groups: SUCCESS 2024-01-02 09:10:17,012 - stages.py[INFO]: Cloud-init v. 23.1.2 finished at Tue, 02 Jan 2024 09:10:17 +0000. Datasource DataSourceEc2Local

Shows cloud-init initialization process, module execution, and any errors.

sudo cat /var/log/cloud-init-output.log

Cloud-init v. 23.1.2 running 'init' at Tue, 02 Jan 2024 09:10:15 +0000 Generating public/private rsa key pair

• echo 'Starting user data script' Starting user data script

• yum update -y Loaded plugins: extras_suggestions, langpacks, priorities, update-motd

• systemctl start httpd

• echo 'User data script completed' User data script completed

Contains actual output from your UserData script execution.

curl http://169.254.169.254/latest/user-data

#!/bin/bash yum update -y yum install -y httpd systemctl start httpd systemctl enable httpd echo "

Hello World

" > /var/www/html/index.html

Returns the exact UserData script that was passed to the instance.

sudo journalctl -u cloud-init

Jan 02 09:10:15 ip-172-31-1-100 systemd[1]: Starting Initial cloud-init job (metadata service crawler)... Jan 02 09:10:16 ip-172-31-1-100 cloud-init[1234]: Cloud-init v. 23.1.2 running 'init' at Tue, 02 Jan 2024 09:10:15 +0000 Jan 02 09:10:17 ip-172-31-1-100 systemd[1]: cloud-init.service: Succeeded. Jan 02 09:10:17 ip-172-31-1-100 systemd[1]: Finished Initial cloud-init job (metadata service crawler).

Shows systemd service status and cloud-init service lifecycle.

sudo tail -f /var/log/messages

Jan 2 09:10:15 ip-172-31-1-100 kernel: [ 0.000000] Linux version 5.10.0-1057-aws Jan 2 09:10:16 ip-172-31-1-100 cloud-init: Cloud-init v. 23.1.2 running 'init' Jan 2 09:10:17 ip-172-31-1-100 systemd: Started Initial cloud-init job

Live system log output including cloud-init messages and any script errors.

If UserData failed, you'll see error messages, stack traces, or the logs will stop abruptly where the failure occurred.