kubernetes/kops · error

image name specification not recognized: %q

Error message

image name specification not recognized: %q

What it means

Returned by resolveImage (aws_cloud.go:1740) when the image name argument cannot be parsed into a known spec format. kops accepts an AMI ID, an owner-alias/name pair, or a bare name; anything else is rejected before any EC2 call.

Source

Thrown at upup/pkg/fi/cloudup/awsup/aws_cloud.go:1740

		if err != nil {
			return nil, err
		}

		request.ImageIds = []string{image}
	} else {
		// Either <imagename> or <owner>/<imagename>
		tokens := strings.SplitN(name, "/", 2)
		if len(tokens) == 1 {
			// self is a well-known value in the DescribeImages call
			request.Owners = []string{"self"}
			request.Filters = append(request.Filters, NewEC2Filter("name", name))
		} else if len(tokens) == 2 {
			owner := ResolveImageOwnerAlias(tokens[0])

			request.Owners = []string{owner}
			request.Filters = append(request.Filters, NewEC2Filter("name", tokens[1]))
		} else {
			return nil, fmt.Errorf("image name specification not recognized: %q", name)
		}
	}

	var image *ec2types.Image
	paginator := ec2.NewDescribeImagesPaginator(ec2Client, request)
	for paginator.HasMorePages() {
		page, err := paginator.NextPage(ctx)
		if err != nil {
			return nil, fmt.Errorf("error listing images: %v", err)
		}

		for _, v := range page.Images {
			if image == nil {
				image = &v
			} else {
				itime, _ := time.Parse(time.RFC3339, *image.CreationDate)
				vtime, _ := time.Parse(time.RFC3339, *v.CreationDate)
				if vtime.After(itime) {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Use one of the supported forms: a bare image name, `owner/name` (2 tokens), or an explicit ami-ID
2. Convert the 3-part public AMI path into `owner/name`, e.g. `099720109477/ubuntu-jammy-22.04-amd64-server-*`
3. Or resolve the path to a concrete AMI ID with `aws ec2 describe-images --owners 099720109477 --filters Name=name,Values=...` and set that AMI ID in the spec
4. Check for typos, spaces, or duplicate slashes in the kops `kubernetesVersion`/AMI configuration

Example fix

// before
KOPS_STATE_STORE=... kops create cluster --image 099720109477/ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*
// after
kops create cluster --image 099720109477/ubuntu-jammy-22.04-amd64-server-*

// Validate the image spec token count before handing it to kops
parts := strings.Split(name, "/")
if len(parts) != 1 && len(parts) != 2 {
	return fmt.Errorf("unsupported image spec %q: use NAME, OWNER/NAME, or an ami ID", name)
}

func isSupportedImageSpec(name string) bool {
	parts := strings.Split(name, "/")
	return len(parts) == 1 || len(parts) == 2
}

When it happens

Trigger: The `name` string splits into an unexpected number of tokens — e.g. more than one `/` separator, or a form with 3+ tokens that matches neither `account-id/name` nor the single-name pattern.

Common situations: Users pass a full AMI path like `099720109477/ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*` (3 slash-separated segments) where kops only supports `owner/name` or a plain name; extra whitespace or a trailing slash also breaks parsing.

Related errors

• error listing images: %v
• could not find Image for %q
• unable to resolve image %q: not found
• image %q has no root device name
• DIGITALOCEAN_ACCESS_TOKEN is required

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