What causes "error listing Akamai (Linode) VPC Subnets: %w" in kubernetes/kops?

Verify the API token is valid (LINODE_API_TOKEN) and has read access

error listing Akamai (Linode) VPC Subnets: %w

Error message

error listing Akamai (Linode) VPC Subnets: %w

What it means

Subnet.Find wraps the linodego ListVPCSubnets error when enumerating subnets of the target VPC. It fires on API failures (auth, rate limit, unknown VPC ID), preventing the task from determining the subnet's current state.

Source

Thrown at upup/pkg/fi/cloudup/linodetasks/subnet.go:68

func (v *Subnet) Find(c *fi.CloudupContext) (*Subnet, error) {
	cloud := c.T.Cloud.(linode.LinodeCloud)

	if v.VPC == nil {
		return nil, fmt.Errorf("Subnet.VPC is required")
	}
	if v.VPC.ID == nil {
		if v.VPC.Name != nil {
			if _, ok := c.Target.(*fi.CloudupDryRunTarget); ok {
				return nil, nil
			}
			return nil, fi.NewTryAgainLaterError("waiting for VPC ID")
		}
		return nil, fmt.Errorf("Subnet.VPC.ID is required")
	}

	subnets, err := cloud.Client().ListVPCSubnets(c.Context(), fi.ValueOf(v.VPC.ID), nil)
	if err != nil {
		return nil, fmt.Errorf("error listing Akamai (Linode) VPC Subnets: %w", err)
	}

	var foundByName *linodego.VPCSubnet
	var foundByIPv4 *linodego.VPCSubnet
	name := fi.ValueOf(v.Name)
	ipv4 := fi.ValueOf(v.IPv4)
	for i := range subnets {
		candidate := &subnets[i]
		if candidate.Label == name {
			if foundByName != nil {
				return nil, fmt.Errorf("found multiple Akamai (Linode) VPC Subnets named %q", name)
			}
			foundByName = candidate
		}
		if ipv4 != "" && candidate.IPv4 == ipv4 {
			if foundByIPv4 == nil {
				foundByIPv4 = candidate
			}

View on GitHub (pinned to 4c8573c808)

Solutions

Verify the API token is valid (LINODE_API_TOKEN) and has read access
Confirm the VPC ID still exists on the account (linode-cli vpcs list)
Re-run kops update — transient API/network errors often resolve on retry
Check the wrapped inner error for the exact HTTP status and message

Example fix

// before
export LINODE_API_TOKEN=bad-token
// after
export LINODE_API_TOKEN=<valid-rw-token>
kops update cluster --yes

Defensive patterns

Strategy: retry

Validate before calling

vpcs, _ := client.ListVPCs(ctx, nil)
found := false
for _, v := range vpcs {
    if fi.ValueOf(v.ID) == vpcID { found = true }
}
if !found { return fmt.Errorf("VPC %d no longer exists", vpcID) }

Try / catch

subnets, err := client.ListVPCSubnets(ctx, vpcID, nil)
if err != nil {
    var le *linodego.Error
    if errors.As(err, &le) && (le.Code == 429 || le.Code >= 500) {
        return retryWithBackoff()
    }
    return fmt.Errorf("error listing Akamai (Linode) VPC Subnets: %w", err)
}

Prevention

Keep LINODE_API_TOKEN valid and scoped
Don't delete VPCs out-of-band while kops manages them
Add backoff/retry for transient Linode API errors

When it happens

Trigger: cloud.Client().ListVPCSubnets(ctx, vpcID, nil) returns an error — auth failure, invalid VPC ID, rate limiting, or API outage.

Common situations: Expired Linode API token, VPC deleted out-of-band so the stored ID no longer exists, or transient network problems during kops update.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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