What causes "failed to find network %q: %w" in kubernetes/kops?

Inspect the wrapped cause (%w) in the error message to identify the actual API failure.

failed to find network %q: %w

Error message

failed to find network %q: %w

What it means

The Hetzner Cloud API call client.Get(context.TODO(), idOrName) in the Network task's Find returned an error while looking up the cluster network by ID or name. This wraps the underlying API error (auth failure, network unreachable, rate limit, or transient Hetzner API error), so the original cause is always included via %w.

Source

Thrown at upup/pkg/fi/cloudup/hetznertasks/network.go:63

var _ fi.CompareWithID = (*Network)(nil)

func (v *Network) CompareWithID() *string {
	return v.ID
}

func (v *Network) Find(c *fi.CloudupContext) (*Network, error) {
	cloud := c.T.Cloud.(hetzner.HetznerCloud)
	client := cloud.NetworkClient()

	idOrName := fi.ValueOf(v.Name)
	if v.ID != nil {
		idOrName = fi.ValueOf(v.ID)
	}

	network, _, err := client.Get(context.TODO(), idOrName)
	if err != nil {
		return nil, fmt.Errorf("failed to find network %q: %w", idOrName, err)
	}
	if network == nil {
		if v.ID != nil {
			return nil, fmt.Errorf("failed to find network %q", idOrName)
		}
		return nil, nil
	}

	matches := &Network{
		Name:      v.Name,
		Lifecycle: v.Lifecycle,
		ID:        new(strconv.FormatInt(network.ID, 10)),
	}

	if v.ID == nil {
		matches.IPRange = network.IPRange.String()
		matches.Labels = network.Labels
		matches.Region = v.Region

View on GitHub (pinned to 4c8573c808)

Solutions

Inspect the wrapped cause (%w) in the error message to identify the actual API failure.
Verify the Hetzner API token is valid, has network read permissions, and belongs to the project containing the network.
Test connectivity: `curl -H "Authorization: Bearer $HCLOUD_TOKEN" https://api.hetzner.cloud/v1/networks`.
If rate limited or transient (429/5xx), retry reconciliation after a short delay.

Example fix

null

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: verify token works before running kops
curl -fsS -H "Authorization: Bearer $HCLOUD_TOKEN" https://api.hetzner.cloud/v1/networks > /dev/null || echo "Hetzner API unreachable or token invalid"

Try / catch

if err := runKopsUpdate(); err != nil {
	var apiErr *hcloud.ErrorResponse
	if errors.As(err, &apiErr) {
		switch apiErr.Code {
		hcloud.ErrorCodeUnauthorized, hcloud.ErrorCodeForbidden:
			// fix HCLOUD_TOKEN / project permissions
		default:
			// transient: retry with backoff
		}
	}
}

Prevention

Keep HCLOUD_TOKEN valid and scoped to the correct project with network read permissions.
Preflight-check API connectivity before long update runs.
Watch for 429 rate limits when running many concurrent kops operations.

When it happens

Trigger: Find in upup/pkg/fi/cloudup/hetznertasks/network.go:63 calls client.Get(ctx, idOrName) and the Hetzner API returns a non-nil error — e.g. invalid HCLOUD_TOKEN, 401/403 unauthorized, rate limiting (429), timeouts, or DNS/connectivity failures.

Common situations: Missing or expired Hetzner API token in the environment; wrong project (network lives in a different Hetzner project than the token can see); corporate proxy/firewall blocking api.hetzner.cloud; Hetzner API outage or rate limiting during reconciliation.

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/402ab00ab7424dc8. Report an issue: GitHub.