kubernetes/kops · error

unable to resolve image: %q: not found

Error message

unable to resolve image: %q: not found

What it means

The sibling of the resolve-failure case: cloud.ResolveImage succeeded (nil error) but returned nil, meaning no AMI matched the requested image spec. buildRootDevice reports 'unable to resolve image: %q: not found'. kOps cannot construct the root device mapping without a concrete AMI.

Source

Thrown at upup/pkg/fi/cloudup/awstasks/launchtemplate.go:118

// CompareWithID implements the comparable interface
func (t *LaunchTemplate) CompareWithID() *string {
	return t.ID
}

// buildRootDevice is responsible for retrieving a boot device mapping from the image name
func (t *LaunchTemplate) buildRootDevice(cloud awsup.AWSCloud) (map[string]*BlockDeviceMapping, error) {
	image := fi.ValueOf(t.ImageID)
	if image == "" {
		return map[string]*BlockDeviceMapping{}, nil
	}

	// @step: resolve the image ami
	img, err := cloud.ResolveImage(image)
	if err != nil {
		return nil, fmt.Errorf("unable to resolve image: %q: %v", image, err)
	} else if img == nil {
		return nil, fmt.Errorf("unable to resolve image: %q: not found", image)
	}

	b := &BlockDeviceMapping{
		EbsDeleteOnTermination: aws.Bool(true),
		EbsVolumeSize:          t.RootVolumeSize,
		EbsVolumeType:          t.RootVolumeType,
		EbsVolumeIops:          t.RootVolumeIops,
		EbsVolumeThroughput:    t.RootVolumeThroughput,
		EbsEncrypted:           t.RootVolumeEncryption,
	}
	if aws.ToBool(t.RootVolumeEncryption) && aws.ToString(t.RootVolumeKmsKey) != "" {
		b.EbsKmsKey = t.RootVolumeKmsKey
	}

	bm := map[string]*BlockDeviceMapping{
		aws.ToString(img.RootDeviceName): b,
	}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Set a valid AMI ID for the target region (kops toolbox cluster-config, or spec field image) or use a supported kops image alias.
2. Verify the AMI exists: aws ec2 describe-images --image-ids ami-... --region <region>.
3. Upgrade kops - newer versions update image aliases to currently published AMIs.
4. Check the AMI is shared with/owned by your account and not deregistered.

Example fix

// before
image: ami-0123456789deadbeef  // deregistered
// after
image: ami-0abcdef1234567890  // current in us-east-1

// before apply: confirm the AMI exists in-region and is visible
aws ec2 describe-images --region $REGION --image-ids $IMAGE --query 'Images[*].ImageId'
// empty output => not found; pick a different image

if strings.Contains(err.Error(), ": not found") { update the image field to a current AMI/alias and re-apply }

When it happens

Trigger: RenderAWS/RenderTerraform -> buildRootDevice where ResolveImage finds zero matching images - e.g. an AMI id that doesn't exist in the region, an image alias with no matching DescribeImages result, or a deleted/deregistered AMI.

Common situations: AMI deregistered by upstream (base image removed); wrong region (AMI is region-local); typo'd ami- id; using an image alias for a release that is no longer published; encrypted/shared AMI not visible to the account.

Related errors

• unable to resolve image: %q: %v
• failed to build root device: %w
• DIGITALOCEAN_ACCESS_TOKEN is required
• errShutdown
• expected a aws.Cloud provider

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/09d9c0133535a39e. Report an issue: GitHub.