{"record":{"id":"1df912ce9b17e335","repo":"kubernetes/kops","slug":"unable-to-resolve-image-q-v","errorCode":null,"errorMessage":"unable to resolve image: %q: %v","messagePattern":"unable to resolve image: %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"upup/pkg/fi/cloudup/awstasks/launchtemplate.go","lineNumber":116,"sourceCode":"\t_ fi.CloudupDeletion          = &deleteLaunchTemplate{}\n)\n\n// CompareWithID implements the comparable interface\nfunc (t *LaunchTemplate) CompareWithID() *string {\n\treturn t.ID\n}\n\n// buildRootDevice is responsible for retrieving a boot device mapping from the image name\nfunc (t *LaunchTemplate) buildRootDevice(cloud awsup.AWSCloud) (map[string]*BlockDeviceMapping, error) {\n\timage := fi.ValueOf(t.ImageID)\n\tif image == \"\" {\n\t\treturn map[string]*BlockDeviceMapping{}, nil\n\t}\n\n\t// @step: resolve the image ami\n\timg, err := cloud.ResolveImage(image)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to resolve image: %q: %v\", image, err)\n\t} else if img == nil {\n\t\treturn nil, fmt.Errorf(\"unable to resolve image: %q: not found\", image)\n\t}\n\n\tb := &BlockDeviceMapping{\n\t\tEbsDeleteOnTermination: aws.Bool(true),\n\t\tEbsVolumeSize:          t.RootVolumeSize,\n\t\tEbsVolumeType:          t.RootVolumeType,\n\t\tEbsVolumeIops:          t.RootVolumeIops,\n\t\tEbsVolumeThroughput:    t.RootVolumeThroughput,\n\t\tEbsEncrypted:           t.RootVolumeEncryption,\n\t}\n\tif aws.ToBool(t.RootVolumeEncryption) && aws.ToString(t.RootVolumeKmsKey) != \"\" {\n\t\tb.EbsKmsKey = t.RootVolumeKmsKey\n\t}\n\n\tbm := map[string]*BlockDeviceMapping{\n\t\taws.ToString(img.RootDeviceName): b,","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/upup/pkg/fi/cloudup/awstasks/launchtemplate.go#L98-L134","documentation":"buildRootDevice resolves the AMI for a launch template's root block device mapping via cloud.ResolveImage(image). If ResolveImage returns an error (AWS DescribeImages failure, multiple/ambiguous matches, invalid image spec), the error is wrapped with the image name. This is distinct from the 'not found' variant: here the lookup itself failed.","triggerScenarios":"RenderAWS or RenderTerraform calls buildRootDevice; cloud.ResolveImage(image) returns non-nil error - e.g. DescribeImages API error, ambiguous image query returning multiple results, or an unparseable image identifier.","commonSituations":"Image alias/name matching multiple AMIs after owner published new images; AWS API error/throttling during DescribeImages; malformed ami string in the InstanceGroup's image field; region where the AMI is not available.","solutions":["Read the wrapped error: if ambiguous, pin the image to a specific AMI ID or add an owner filter.","Verify the image value in the InstanceGroup (kops get ig --name -o yaml) is a valid AMI id (ami-...) or supported alias.","Retry if the underlying error was throttling/transient.","Confirm the AMI exists in the cluster's region."],"exampleFix":"// before (InstanceGroup)\nimage: 099720109477/ubuntu-jammy-22.04  // ambiguous\n// after\nimage: ami-0abcdef1234567890","handlingStrategy":"validation","validationCode":"// verify the image resolves before apply\naws ec2 describe-images --region $REGION --image-ids $IMAGE\n// or for names: aws ec2 describe-images --filters Name=name,Values=$IMAGE_NAME Name=owner-alias,Values=amazon","typeGuard":"func isAMIID(image string) bool { return regexp.MustCompile(`^ami-[0-9a-f]{8,17}$`).MatchString(image) }","tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"unable to resolve image\") { check wrapped cause; pin a specific AMI ID and retry }","preventionTips":["Pin images to explicit AMI IDs to avoid ambiguous name matches.","Keep the AMI valid for the cluster's region.","Retry transient DescribeImages errors with backoff."],"tags":["aws","ami","image-resolution","launch-template"],"backgroundTag":"ami-resolution-failed","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}