{"record":{"id":"983f030c1dc0660b","repo":"kubernetes/kops","slug":"instance-userdata-was-too-large-d-bytes","errorCode":null,"errorMessage":"Instance UserData was too large (%d bytes)","messagePattern":"Instance UserData was too large \\((.+?) bytes\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"upup/pkg/fi/cloudup/awstasks/instance.go","lineNumber":281,"sourceCode":"\t\t\trequest.BlockDeviceMappings = []ec2types.BlockDeviceMapping{}\n\t\t\tfor deviceName, bdm := range blockDeviceMappings {\n\t\t\t\trequest.BlockDeviceMappings = append(request.BlockDeviceMappings, bdm.ToEC2(deviceName))\n\t\t\t}\n\t\t}\n\n\t\tif e.UserData != nil {\n\t\t\td, err := fi.ResourceAsBytes(e.UserData)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"error rendering Instance UserData: %v\", err)\n\t\t\t}\n\t\t\tif len(d) > MaxUserDataSize {\n\t\t\t\t// TODO: Re-enable gzip?\n\t\t\t\t// But it exposes some bugs in the AWS console, so if we can avoid it, we should\n\t\t\t\t//d, err = fi.GzipBytes(d)\n\t\t\t\t//if err != nil {\n\t\t\t\t//\treturn fmt.Errorf(\"error while gzipping UserData: %v\", err)\n\t\t\t\t//}\n\t\t\t\treturn fmt.Errorf(\"Instance UserData was too large (%d bytes)\", len(d))\n\t\t\t}\n\t\t\trequest.UserData = aws.String(base64.StdEncoding.EncodeToString(d))\n\t\t}\n\n\t\tif e.IAMInstanceProfile != nil {\n\t\t\trequest.IamInstanceProfile = &ec2types.IamInstanceProfileSpecification{\n\t\t\t\tName: e.IAMInstanceProfile.Name,\n\t\t\t}\n\t\t}\n\n\t\tresponse, err := t.Cloud.EC2().RunInstances(ctx, request)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"error creating Instance: %v\", err)\n\t\t}\n\n\t\te.ID = response.Instances[0].InstanceId\n\t}\n","sourceCodeStart":263,"sourceCodeEnd":299,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/upup/pkg/fi/cloudup/awstasks/instance.go#L263-L299","documentation":"EC2 limits UserData to MaxUserDataSize (16 KiB for RunInstances). RenderAWS reads the full UserData and, before encoding it into the RunInstances request, rejects anything larger. The gzip workaround is intentionally disabled because it breaks the AWS console, so oversized UserData is a hard failure and no instance is created.","triggerScenarios":"Creating an EC2 instance whose rendered UserData byte length exceeds MaxUserDataSize (16384 bytes), typically a large bootstrap script or embedded nodeup payload.","commonSituations":"Very large cluster bootstrap scripts; embedding manifests/configs directly in UserData; multi-line shell scripts grown by repeated edits; region/config changes that balloon generated scripts; accidentally inlining a binary or large config into the igconfig userData field.","solutions":["Shrink the UserData script: remove comments/whitespace or split into multiple smaller scripts.","Move heavy work off UserData: download and run a bootstrap script from S3/HTTPS instead of inlining it.","Use kOps' built-in nodeup bootstrap (default) rather than custom full-script UserData.","Enable/configure the gzip path locally (fi.GzipBytes) if console rendering is not a concern for you.","Check `wc -c` on the rendered script and re-run kops update after trimming."],"exampleFix":"// before (RenderAWS path)\nif len(d) > MaxUserDataSize {\n\treturn fmt.Errorf(\"Instance UserData was too large (%d bytes)\", len(d))\n}\n// after (consumer-side shrink: fetch script instead of inline)\n// user-data:\n//   #!/bin/sh\n//   curl -sSf https://s3.amazonaws.com/my-bucket/bootstrap.sh | bash","handlingStrategy":"validation","validationCode":"// Check rendered UserData size before applying\nconst maxUserDataSize = 16384 // EC2 RunInstances limit used by kOps\n\nfunc validateUserData(scriptPath string) error {\n\td, err := os.ReadFile(scriptPath)\n\tif err != nil {\n\t\treturn err\n\t}\n\tif len(d) > maxUserDataSize {\n\t\treturn fmt.Errorf(\"Instance UserData was too large (%d bytes); max is %d\", len(d), maxUserDataSize)\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"err := applyCluster(ctx)\nif err != nil && strings.Contains(err.Error(), \"UserData was too large\") {\n\treturn fmt.Errorf(\"shrink or externalize the bootstrap script, then re-run: %w\", err)\n}\nreturn err","preventionTips":["Keep UserData scripts well under 16 KiB; lint their size in CI (`wc -c`).","Move large payloads to S3/HTTPS and fetch them from a small bootstrap script.","Prefer kOps' built-in nodeup mechanism over fully custom UserData.","Strip comments and unnecessary content from generated scripts before packaging."],"tags":["aws","ec2","userdata","limit","instance-creation"],"backgroundTag":"payload-too-large","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T07:17:12.445Z"}