cilium/cilium · error

pod doesn't have HostIP of family %s

Error message

pod doesn't have HostIP of family %s

What it means

GetPodHostIPByFamily scans pod.Status.HostIPs looking for an address whose family matches the requested IPFamily (IPv4 or IPv6). If no HostIP entry matches, the helper returns this error. It is thrown when a pod simply has no host IP of the requested family, typically because the node/cluster is single-stack.

Source

Thrown at cilium-cli/connectivity/check/context.go:1460

		ct.params.MultiCluster == ""
}

func (ct *ConnectivityTest) IsSocketLBFull() bool {
	socketLBEnabled, _ := ct.Features.MatchRequirements(features.RequireEnabled(features.KPRSocketLB))
	if socketLBEnabled {
		socketLBHostnsOnly, _ := ct.Features.MatchRequirements(features.RequireEnabled(features.KPRSocketLBHostnsOnly))
		return !socketLBHostnsOnly
	}
	return false
}

func (ct *ConnectivityTest) GetPodHostIPByFamily(pod Pod, ipFam features.IPFamily) (string, error) {
	for _, addr := range pod.Pod.Status.HostIPs {
		if features.GetIPFamily(addr.IP) == ipFam {
			return addr.IP, nil
		}
	}
	return "", fmt.Errorf("pod doesn't have HostIP of family %s", ipFam)
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Verify the cluster/node actually supports the requested family: kubectl get node -o jsonpath='{.items[*].status.addresses}' and check for the matching address type.
2. Wait for the pod to be Running before resolving its HostIP (pods that are Pending have no HostIPs).
3. Run the test with an IP family the cluster supports (e.g. dual-stack cluster for ipv6 tests), or enable dual-stack on kubelet/kube-apiserver.

Example fix

// before: request IPv6 on a single-stack cluster
hostIP, err := ct.GetPodHostIPByFamily(pod, features.IPFamilyIPv6)
// after: only request IPv6 when the cluster has the family
if ct.Features().IPFamilyModes[features.IPFamilyIPv6] {
    hostIP, err = ct.GetPodHostIPByFamily(pod, features.IPFamilyIPv6)
}

// ensure cluster supports the family before requesting host IPs
if ipFam == features.IPFamilyIPv6 && !ct.Features().IPFamilyModes[features.IPFamilyIPv6] {
    return errors.New("cluster has no IPv6 support; skip IPv6 host IP lookup")
}
if pod.Pod.Status.Phase != v1.PodRunning || len(pod.Pod.Status.HostIPs) == 0 {
    return errors.New("pod not running; no HostIPs assigned yet")
}

hostIP, err := ct.GetPodHostIPByFamily(pod, ipFam)
if err != nil {
    if strings.HasPrefix(err.Error(), "pod doesn't have HostIP of family") {
        hostIP, err = ct.GetPodHostIPByFamily(pod, features.IPFamilyV4) // fallback family
    }
    if err != nil { return err }
}

When it happens

Trigger: Requesting features.IPFamilyIPv6 for a pod on an IPv4-only node (or vice versa); a pod not yet scheduled/running so Status.HostIPs is empty; kubelet configured without the requested dual-stack IPFamily.

Common situations: Running connectivity tests with --ip-family ipv6 against a cluster that was never provisioned for IPv6 (no dual-stack kube-apiserver/kubelet, no IPv6 pod CIDR); test pods still Pending so no host IPs are assigned yet.

Related errors

• no link found inside container
• failed to %s static route: %w
• unable to allocate health IPv6: %w, see https://cilium.link/
• failed to port forward: %w
• endpoint sync cannot take ownership of CEP that is not local

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/1e517a1680687003. Report an issue: GitHub.