kubernetes/kops · error

error creating Route: %s

Error message

error creating Route: %s

What it means

This error wraps a failed EC2 CreateRoute API call during Route task creation, reporting the AWS error message. Special-cased: if the error code is InvalidNatGatewayID.NotFound, kOps instead returns a retryable TryAgainLaterError, because a NAT gateway may still be propagating when the route is created. All other failures become this terminal error.

Source

Thrown at upup/pkg/fi/cloudup/awstasks/route.go:231

			request.VpcPeeringConnectionId = e.VPCPeeringConnectionID
		}

		if e.Instance != nil {
			request.InstanceId = checkNotNil(e.Instance.ID)
		}

		klog.V(2).Infof("Creating Route with RouteTable:%q CIDR:%q IPv6CIDR:%q",
			aws.ToString(e.RouteTable.ID), aws.ToString(e.CIDR), aws.ToString(e.IPv6CIDR))

		response, err := t.Cloud.EC2().CreateRoute(ctx, request)
		if err != nil {
			code := awsup.AWSErrorCode(err)
			message := awsup.AWSErrorMessage(err)
			if code == "InvalidNatGatewayID.NotFound" {
				klog.V(4).Infof("error creating Route: %s", message)
				return fi.NewTryAgainLaterError("waiting for the NAT Gateway to be created")
			}
			return fmt.Errorf("error creating Route: %s", message)
		}

		if !aws.ToBool(response.Return) {
			return fmt.Errorf("create Route request failed: %v", response)
		}
	} else {
		request := &ec2.ReplaceRouteInput{}
		request.RouteTableId = checkNotNil(e.RouteTable.ID)

		if e.CIDR != nil || e.IPv6CIDR != nil {
			request.DestinationCidrBlock = e.CIDR
			request.DestinationIpv6CidrBlock = e.IPv6CIDR
		} else {
			klog.Fatal("both CIDR and IPv6CIDR were unexpectedly nil")
		}

		if e.InternetGateway == nil && e.NatGateway == nil && e.TransitGatewayID == nil && e.VPCPeeringConnectionID == nil {
			return fmt.Errorf("missing target for route")

View on GitHub (pinned to 4c8573c808)

Solutions

1. Read the AWS message in the error to identify the specific API failure
2. If RouteAlreadyExists, remove the duplicate route from the cluster spec or delete the stale route in AWS
3. Verify all referenced IDs (route table, IGW, NAT, TGW) exist in the region
4. Check IAM permissions for ec2:CreateRoute
5. Re-run kops update cluster — transient propagation issues are already retried automatically

// Pre-check that the target resource exists
aws ec2 describe-nat-gateways --nat-gateway-ids nat-0abc123 --region us-east-1
aws ec2 describe-internet-gateways --internet-gateway-ids igw-0abc123 --region us-east-1

_, err := cloud.EC2().CreateRoute(ctx, req)
if err != nil {
	if awsup.AWSErrorCode(err) == "InvalidNatGatewayID.NotFound" {
		return fi.NewTryAgainLaterError("waiting for the NAT Gateway to be created")
	}
	if awsup.AWSErrorCode(err) == "RouteAlreadyExists" {
		// remove the duplicate route from the spec or delete stale route
	}
	return fmt.Errorf("error creating Route: %s", awsup.AWSErrorMessage(err))
}

When it happens

Trigger: CreateRoute failing for reasons other than NAT-gateway propagation: invalid RouteTableId or target ID, duplicate route for the destination CIDR, route table not found, or permission denied.

Common situations: A route already exists for the same CIDR (RouteAlreadyExists); referencing a deleted NAT/IGW/TGW; IAM missing ec2:CreateRoute; CIDR overlap with an existing route in the same table.

Related errors

• create Route request failed: %v
• describing instance for arn %q
• error terminating instances: %v
• error describing instances: %v
• error describing addresses: %v

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