{"record":{"id":"8666a8a4dd708479","repo":"kubernetes/kops","slug":"failed-to-build-root-device-w","errorCode":null,"errorMessage":"failed to build root device: %w","messagePattern":"failed to build root device: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"upup/pkg/fi/cloudup/awstasks/launchtemplate_target_api.go","lineNumber":68,"sourceCode":"\t\tMetadataOptions: &ec2types.LaunchTemplateInstanceMetadataOptionsRequest{\n\t\t\tHttpPutResponseHopLimit: t.HTTPPutResponseHopLimit,\n\t\t\tHttpTokens:              fi.ValueOf(t.HTTPTokens),\n\t\t\tHttpProtocolIpv6:        fi.ValueOf(t.HTTPProtocolIPv6),\n\t\t},\n\t\tNetworkInterfaces: []ec2types.LaunchTemplateInstanceNetworkInterfaceSpecificationRequest{\n\t\t\t{\n\t\t\t\tAssociatePublicIpAddress: t.AssociatePublicIP,\n\t\t\t\tDeleteOnTermination:      aws.Bool(true),\n\t\t\t\tDeviceIndex:              new(int32(0)),\n\t\t\t\tIpv6AddressCount:         t.IPv6AddressCount,\n\t\t\t},\n\t\t},\n\t}\n\n\t// @step: add the actual block device mappings\n\trootDevices, err := t.buildRootDevice(c.Cloud)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to build root device: %w\", err)\n\t}\n\tephemeralDevices, err := buildEphemeralDevices(c.Cloud, fi.ValueOf(t.InstanceType))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to build ephemeral devices: %w\", err)\n\t}\n\tadditionalDevices, err := buildAdditionalDevices(t.BlockDeviceMappings)\n\tif err != nil {\n\t\treturn err\n\t}\n\tfor _, x := range []map[string]*BlockDeviceMapping{rootDevices, ephemeralDevices, additionalDevices} {\n\t\tfor name, device := range x {\n\t\t\tdata.BlockDeviceMappings = append(data.BlockDeviceMappings, device.ToLaunchTemplateBootDeviceRequest(name))\n\t\t}\n\t}\n\n\t// @step: add the ssh key\n\tif t.SSHKey != nil {\n\t\tdata.KeyName = t.SSHKey.Name","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/upup/pkg/fi/cloudup/awstasks/launchtemplate_target_api.go#L50-L86","documentation":"RenderAWS for the LaunchTemplate task calls t.buildRootDevice(c.Cloud) to compute the root volume block device mapping (resolving the AMI and building the EBS mapping). Any failure inside buildRootDevice - most commonly AMI resolution errors - is wrapped as 'failed to build root device'.","triggerScenarios":"RenderAWS on a launchtemplate task where buildRootDevice returns an error: ResolveImage API failure, image not found, or nil root volume info while constructing the BlockDeviceMapping.","commonSituations":"Invalid/unresolvable AMI in the InstanceGroup; region mismatch; AWS DescribeImages throttling; misconfigured RootVolumeSize/RootVolumeType interacting with an unresolvable image.","solutions":["Inspect the wrapped (%w) cause - usually ami-resolution or not-found - and fix the image field.","Pin the InstanceGroup image to a valid region-specific AMI id.","Retry the apply if the cause was an AWS API transient error.","Validate InstanceGroup spec (kops validate / kops get ig) before applying."],"exampleFix":"// before\nimage: unknown-alias\n// after\nimage: ami-0abcdef1234567890","handlingStrategy":"validation","validationCode":"// pre-flight: ensure image resolves so buildRootDevice succeeds\naws ec2 describe-images --region $REGION --image-ids $(kops get ig nodes -o json | jq -r .spec.image)","typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"failed to build root device\") { inspect %w cause; fix the image/volume config; re-apply }","preventionTips":["Validate InstanceGroup spec (image, rootVolumeSize, rootVolumeType) before apply.","Keep kops updated for new instance/image metadata.","Use explicit AMI IDs for reproducibility."],"tags":["aws","launch-template","root-volume","ami"],"backgroundTag":"root-device-build-failed","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"}