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

Verify the Region supports VPCs and is spelled correctly in the cluster spec

error creating Akamai (Linode) VPC %q: %w

Error message

error creating Akamai (Linode) VPC %q: %w

What it means

This error wraps a failure from the Linode API CreateVPC call in RenderLinode, invoked when Find() found no existing VPC and kops must provision one with the spec's label, description, and region. The underlying linodego error (validation, quota, region, auth) is preserved via %w.

Source

Thrown at upup/pkg/fi/cloudup/linodetasks/vpc.go:126

			return fi.RequiredField("Name")
		}
		if expected.Region == nil {
			return fi.RequiredField("Region")
		}
	}

	return nil
}

func (_ *VPC) RenderLinode(t *linode.APITarget, actual, expected, changes *VPC) error {
	if actual == nil {
		vpc, err := t.Cloud.Client().CreateVPC(context.Background(), linodego.VPCCreateOptions{
			Label:       fi.ValueOf(expected.Name),
			Description: fi.ValueOf(expected.Description),
			Region:      fi.ValueOf(expected.Region),
		})
		if err != nil {
			return fmt.Errorf("error creating Akamai (Linode) VPC %q: %w", fi.ValueOf(expected.Name), err)
		}
		expected.ID = new(vpc.ID)
		return nil
	}

	if changes == nil || (changes.Name == nil && changes.Description == nil) {
		expected.ID = actual.ID
		return nil
	}

	vpc, err := t.Cloud.Client().UpdateVPC(context.Background(), fi.ValueOf(actual.ID), linodego.VPCUpdateOptions{
		Label:       fi.ValueOf(expected.Name),
		Description: fi.ValueOf(expected.Description),
	})
	if err != nil {
		return fmt.Errorf("error updating Akamai (Linode) VPC %q: %w", fi.ValueOf(expected.Name), err)
	}
	expected.ID = new(vpc.ID)

View on GitHub (pinned to 4c8573c808)

Solutions

Verify the Region supports VPCs and is spelled correctly in the cluster spec
Check the wrapped linodego error for quota messages; delete unused VPCs or request a limit increase
Ensure the VPC label (expected.Name) meets Linode label rules (1-64 chars, alphanumeric/dashes)
Confirm the API token has vpcs:read_write scope
Retry on transient 5xx; the task re-runs safely after Find() returns nil

Example fix

// before: unsupported region for VPC
region: us-southeast   # if VPC unavailable there
// after: pick a VPC-capable region
region: us-east

Defensive patterns

Strategy: validation

Validate before calling

func validateVPCCreate(name, region string) error {
    if len(name) == 0 || len(name) > 64 {
        return fmt.Errorf("VPC name %q must be 1-64 chars for a valid Linode label", name)
    }
    if !vpcCapableRegions[region] {
        return fmt.Errorf("region %q does not support VPCs", region)
    }
    return nil
}

var vpcCapableRegions = map[string]bool{
    "us-east": true, "us-southeast": true, "us-central": true,
    "eu-west": true, "ap-south": true, // verify current list via linode-cli regions list
}

Type guard

func isVPCQuotaError(err error) bool {
    var apiErr *linodego.Error
    return errors.As(err, &apiErr) && strings.Contains(strings.ToLower(apiErr.Message), "limit")
}

Try / catch

if err := run(); err != nil {
    var apiErr *linodego.Error
    if errors.As(err, &apiErr) {
        if apiErr.Code == 400 && strings.Contains(strings.ToLower(apiErr.Message), "label") {
            return fmt.Errorf("invalid VPC label %q: %w", name, err)
        }
        if apiErr.Code == 429 || apiErr.Code >= 500 {
            time.Sleep(backoff)
            return run() // safe: Find() returns nil until creation succeeds
        }
    }
    return err
}

Prevention

Confirm the region supports VPCs before selecting it in the cluster spec
Keep VPC names within Linode label rules (alphanumeric and dashes, <=64 chars)
Check VPC-per-region quota before multi-cluster bring-up in one region
Use a token with vpcs:read_write scope
Uniquely name VPCs so a prior partial run's VPC is adopted instead of re-created

When it happens

Trigger: CreateVPC rejects the request: label fails Linode validation (length/charset after the spec name is used verbatim), invalid or VPC-unsupported region, account VPC quota exceeded (limit of VPCs per region), invalid token/scopes, or a transient 5xx.

Common situations: Cluster spec uses a region that does not support VPCs; account hit the VPC-per-region limit; VPC label contains invalid characters or exceeds 64 chars; expired API token during new-cluster bring-up.

Related errors

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