SAM Doctor

ERROR REFERENCE

User data is limited to 16384 bytes

EC2 rejected user data larger than 16,384 bytes

EC2 refused the instance or launch-template request because the rendered user data exceeds its 16,384-byte limit. The limit applies to the raw, base64-decoded script — and CloudFormation resolves Fn::Sub and Fn::Base64 before EC2 sees the result, so a template that looks small can exceed the limit after substitution.

WHAT IT MEANS

What this error means

An error occurred (InvalidParameterValue) when calling the RunInstances operation:
User data is limited to 16384 bytes

CREATE_FAILED  AWS::EC2::Instance  Web
Resource handler returned message: "User data is limited to 16384 bytes
(Service: AmazonEC2; Status Code: 400; Error Code: InvalidParameterValue)"

The number is a hard EC2 request limit, not a quota you can raise. It is measured against the decoded bytes that reach EC2, which is why counting characters in the template understates the real size.

SAFE NEXT STEPS

Measure the rendered script, then make it smaller

  1. Measure what was actually sent, not the template text. Base64-decode the rendered user data and count its bytes. For an existing instance, read the current value without changing anything: 
    aws ec2 describe-instance-attribute --instance-id YOUR_INSTANCE \
  --attribute userData --query "UserData.Value" --output text | base64 --decode | wc -c
  2. Shrink the inline script first. Strip comments and blank lines; heredocs and embedded configuration files are usually where the bytes went.
  3. Move the bootstrap body out of user data. Store the real script in S3 or an SSM document, keep a short download-and-run stub in user data, and grant the instance profile read access to it.
  4. Compress or prebake what remains. cloud-init accepts gzip-compressed user data, and setup that rarely changes belongs in the AMI image rather than in the boot script.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the RunInstances error, the CloudFormation resource-handler message, and the InvalidUserData.Malformed wrapper, and runs locally without AWS credentials or log upload. 

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED