kubernetes/kops · error

failed to build root device: %w

Error message

failed to build root device: %w

What it means

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'.

Source

Thrown at upup/pkg/fi/cloudup/awstasks/launchtemplate_target_api.go:68

		MetadataOptions: &ec2types.LaunchTemplateInstanceMetadataOptionsRequest{
			HttpPutResponseHopLimit: t.HTTPPutResponseHopLimit,
			HttpTokens:              fi.ValueOf(t.HTTPTokens),
			HttpProtocolIpv6:        fi.ValueOf(t.HTTPProtocolIPv6),
		},
		NetworkInterfaces: []ec2types.LaunchTemplateInstanceNetworkInterfaceSpecificationRequest{
			{
				AssociatePublicIpAddress: t.AssociatePublicIP,
				DeleteOnTermination:      aws.Bool(true),
				DeviceIndex:              new(int32(0)),
				Ipv6AddressCount:         t.IPv6AddressCount,
			},
		},
	}

	// @step: add the actual block device mappings
	rootDevices, err := t.buildRootDevice(c.Cloud)
	if err != nil {
		return fmt.Errorf("failed to build root device: %w", err)
	}
	ephemeralDevices, err := buildEphemeralDevices(c.Cloud, fi.ValueOf(t.InstanceType))
	if err != nil {
		return fmt.Errorf("failed to build ephemeral devices: %w", err)
	}
	additionalDevices, err := buildAdditionalDevices(t.BlockDeviceMappings)
	if err != nil {
		return err
	}
	for _, x := range []map[string]*BlockDeviceMapping{rootDevices, ephemeralDevices, additionalDevices} {
		for name, device := range x {
			data.BlockDeviceMappings = append(data.BlockDeviceMappings, device.ToLaunchTemplateBootDeviceRequest(name))
		}
	}

	// @step: add the ssh key
	if t.SSHKey != nil {
		data.KeyName = t.SSHKey.Name

View on GitHub (pinned to 4c8573c808)

Solutions

1. Inspect the wrapped (%w) cause - usually ami-resolution or not-found - and fix the image field.
2. Pin the InstanceGroup image to a valid region-specific AMI id.
3. Retry the apply if the cause was an AWS API transient error.
4. Validate InstanceGroup spec (kops validate / kops get ig) before applying.

Example fix

// before
image: unknown-alias
// after
image: ami-0abcdef1234567890

// pre-flight: ensure image resolves so buildRootDevice succeeds
aws ec2 describe-images --region $REGION --image-ids $(kops get ig nodes -o json | jq -r .spec.image)

if strings.Contains(err.Error(), "failed to build root device") { inspect %w cause; fix the image/volume config; re-apply }

When it happens

Trigger: 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.

Common situations: Invalid/unresolvable AMI in the InstanceGroup; region mismatch; AWS DescribeImages throttling; misconfigured RootVolumeSize/RootVolumeType interacting with an unresolvable image.

Related errors

• unable to resolve image: %q: %v
• unable to resolve image: %q: not found
• 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/8666a8a4dd708479. Report an issue: GitHub.