kubernetes/kops · error

failed to list servers: %w

Error message

failed to list servers: %w

What it means

findServerGroups wraps any error returned by GetServers (the Hetzner hcloud /servers list call) with context before propagating it to GetCloudGroups. It means the Hetzner Cloud API listing of servers for the cluster failed, so no cloud instance groups could be computed.

Source

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

				klog.Warningf("Server group %q has no corresponding instance group", name)
			}
			continue
		}

		cloudInstanceGroups[instanceGroup.Name], err = buildCloudInstanceGroup(instanceGroup, serverGroup, nodeMap)
		if err != nil {
			return nil, fmt.Errorf("failed to build cloud instance group for instance group %q: %w", instanceGroup.Name, err)
		}
	}

	return cloudInstanceGroups, nil
}

// findServerGroups finds all server groups belonging to the cluster
func findServerGroups(c *hetznerCloudImplementation, clusterName string) (map[string][]*hcloud.Server, error) {
	servers, err := c.GetServers(clusterName)
	if err != nil {
		return nil, fmt.Errorf("failed to list servers: %w", err)
	}

	serverGroups := make(map[string][]*hcloud.Server)
	for _, server := range servers {
		instanceGroupNameLabel, ok := server.Labels[TagKubernetesInstanceGroup]
		if !ok {
			klog.Warningf("failed to find instance group name for server %s(%d)", server.Name, server.ID)
			continue
		}

		instanceGroupName := fmt.Sprintf("%s-%s", clusterName, instanceGroupNameLabel)
		serverGroups[instanceGroupName] = append(serverGroups[instanceGroupName], server)
	}

	return serverGroups, nil
}

func buildCloudInstanceGroup(ig *kops.InstanceGroup, sg []*hcloud.Server, nodeMap map[string]*v1.Node) (*cloudinstances.CloudInstanceGroup, error) {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Check the wrapped error for the root cause (401 => invalid HCLOUD_TOKEN, timeouts => network, 429 => rate limit).
2. Verify HCLOUD_TOKEN is valid: `curl -H "Authorization: Bearer $HCLOUD_TOKEN" https://api.hetzner.cloud/v1/servers`.
3. Retry the operation; transient network/API failures are common.
4. If rate limited, back off and reduce polling frequency.

// preflight
const ok = process.env.HCLOUD_TOKEN && (await fetch('https://api.hetzner.cloud/v1/servers',{headers:{Authorization:`Bearer ${process.env.HCLOUD_TOKEN}`}})).ok;

var groups *map[string][]*hcloud.Server
for i := 0; i < 3; i++ {
  groups, err = findServerGroups(c, clusterName)
  if err == nil { break }
  time.Sleep(backoff(i)) // retry transient API failures
}
if err != nil { return fmt.Errorf("failed to list servers: %w", err) }

When it happens

Trigger: c.GetServers(clusterName) returns an error: Hetzner API HTTP error, invalid/expired HCLOUD_TOKEN, network timeout, or API rate limiting during the ListServers request.

Common situations: Wrong or revoked API token in HCLOUD_TOKEN env; Hetzner API outage; network egress blocked from the CI/bastion host; hitting hcloud API rate limits on large clusters.

Related errors

• failed to list ssh keys: %w
• failed to list networks: %w
• failed to list firewalls: %w
• failed to list load balancers: %w
• failed to list servers: %w

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