kubernetes/kops · error

image %q must be ami-*, ssm:<parameter>, <name>, or <owner>/

Error message

image %q must be ami-*, ssm:<parameter>, <name>, or <owner>/<name>

What it means

buildKarpenterAMITerms accepts only ami-* ids, ssm: parameters, plain names, or owner/name pairs. An image containing '://' (e.g. a URL or docker-style reference) cannot be mapped to an EC2 AMI term and is rejected with this format error.

Source

Thrown at upup/pkg/fi/cloudup/template_functions_karpenter.go:462

	}

	return &karpenterNodePool{
		APIVersion: karpenterNodePoolAPIGroup + "/v1",
		Kind:       "NodePool",
		Metadata: karpenterObjectMeta{
			Name: ig.Name,
		},
		Spec: spec,
	}, nil
}

func buildKarpenterAMITerms(image string) ([]karpenterAMITerm, error) {
	image = strings.TrimSpace(image)
	if image == "" {
		return nil, fmt.Errorf("image is required")
	}
	if strings.Contains(image, "://") {
		return nil, fmt.Errorf("image %q must be ami-*, ssm:<parameter>, <name>, or <owner>/<name>", image)
	}
	if strings.HasPrefix(image, "ami-") {
		return []karpenterAMITerm{{ID: image}}, nil
	}
	if strings.HasPrefix(image, "ssm:") {
		parameter := strings.TrimPrefix(image, "ssm:")
		if parameter == "" {
			return nil, fmt.Errorf("ssm image parameter is required")
		}
		return []karpenterAMITerm{{SSMParameter: parameter}}, nil
	}

	tokens := strings.SplitN(image, "/", 2)
	if len(tokens) == 1 {
		return []karpenterAMITerm{{Name: image, Owner: "self"}}, nil
	}
	if tokens[0] == "" || tokens[1] == "" {
		return nil, fmt.Errorf("image %q must be ami-*, ssm:<parameter>, <name>, or <owner>/<name>", image)

View on GitHub (pinned to 4c8573c808)

Solutions

1. Replace the URL with a valid AMI id (ami-*), SSM parameter (ssm:<parameter>), image name, or owner/name alias
2. Strip any scheme prefix and use the raw AMI identifier
3. Validate the AMI exists in the target region before re-running update

Example fix

// before
image: https://example.com/my-ami
// after
image: ami-0abcdef1234567890

// reject URL-like image values early
if strings.Contains(image, "://") {
	return fmt.Errorf("image must be ami-*, ssm:<parameter>, <name>, or <owner>/<name>; got %q", image)
}

if err != nil && strings.Contains(err.Error(), "must be ami-*") {
	return fmt.Errorf("image is not an AMI selector: %w", err)
}

When it happens

Trigger: Setting the image field to something like docker://... or https://... (any string containing '://') when building the Karpenter EC2NodeClass AMI terms.

Common situations: Confusing container image references with AMI selectors; pasting a URL from a browser into the image field; copying ECR image URIs instead of AMI identifiers.

Related errors

• image is required
• ssm image parameter is required
• --region is required (when --external)
• instance id for cloud instance member cannot be empty
• unknown load balancer Type: %q

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