failed to get load balancers matching label selector %q: %w

Error message

failed to get load balancers matching label selector %q: %w

What it means

GetLoadBalancers wraps any error from hcloud LoadBalancerClient.AllWithOpts when listing load balancers filtered by the cluster label selector. It indicates the Hetzner Cloud API list request failed; the original hcloud error is wrapped.

Source

Thrown at upup/pkg/fi/cloudup/hetzner/cloud.go:201

		return nil, fmt.Errorf("failed to get firewalls matching label selector %q: %w", labelSelector, err)
	}

	return matches, nil
}

func (c *hetznerCloudImplementation) GetLoadBalancers(clusterName string) ([]*hcloud.LoadBalancer, error) {
	client := c.LoadBalancerClient()

	labelSelector := TagKubernetesClusterName + "=" + clusterName
	listOptions := hcloud.ListOpts{
		PerPage:       50,
		LabelSelector: labelSelector,
	}
	loadBalancerListOptions := hcloud.LoadBalancerListOpts{ListOpts: listOptions}

	matches, err := client.AllWithOpts(context.TODO(), loadBalancerListOptions)
	if err != nil {
		return nil, fmt.Errorf("failed to get load balancers matching label selector %q: %w", labelSelector, err)
	}

	return matches, nil
}

func (c *hetznerCloudImplementation) GetServers(clusterName string) ([]*hcloud.Server, error) {
	client := c.ServerClient()

	labelSelector := TagKubernetesClusterName + "=" + clusterName
	listOptions := hcloud.ListOpts{
		PerPage:       50,
		LabelSelector: labelSelector,
	}
	sortOptions := []string{
		"created:desc",
	}
	serverListOptions := hcloud.ServerListOpts{ListOpts: listOptions, Sort: sortOptions}

View on GitHub (pinned to 4c8573c808)

Solutions

Verify HCLOUD_TOKEN is valid and scoped to the correct Hetzner project
Retry after the rate-limit window if the wrapped error is 429
Check Hetzner status page / API reachability for outages
Unwrap the error (errors.Unwrap) to see the specific hcloud.ErrorCode

Defensive patterns

Strategy: retry

Validate before calling

if os.Getenv("HCLOUD_TOKEN") == "" {
	return fmt.Errorf("HCLOUD_TOKEN must be set before calling GetLoadBalancers")
}

Type guard

var hcloudErr *hcloud.Error
if errors.As(err, &hcloudErr) {
	// branch on hcloudErr.Code
}

Try / catch

lbs, err := cloud.GetLoadBalancers(clusterName)
if err != nil {
	var hErr *hcloud.Error
	if errors.As(err, &hErr) && hErr.Code == hcloud.ErrorCodeRateLimit {
		time.Sleep(hErr.RateLimit.RetryAfter())
		lbs, err = cloud.GetLoadBalancers(clusterName)
	}
}

Prevention

Validate the token with a cheap API call (e.g. client.Server.List) before heavy operations
Back off on 429 before retrying list calls
Watch for token rotation in the Hetzner console
Confirm project/permissions when moving clusters between projects

When it happens

Trigger: Calling GetLoadBalancers with an invalid/missing API token, network failure to api.hetzner.cloud, rate limiting (429), or a server-side 5xx during paginated AllWithOpts listing.

Common situations: kOps validate or delete operations on a Hetzner cluster when the token was rotated or project deleted, or when Hetzner has a partial API outage affecting the load balancer endpoint.

Related errors

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