k3s-io/k3s · error

no IPv4 address found

Error message

no IPv4 address found

What it means

getFirst4Net's sibling getFirst4 in pkg/util/net.go returns the first IPv4 net.IP from a list, or 'no IPv4 address found' when all entries are nil or IPv6. It backs the exported GetFirst4String, used to pick an IPv4 address from settings like --node-ip, advertise addresses, or bind addresses.

Source

Thrown at pkg/util/net.go:56

	for _, elem := range elems {
		if elem == nil || elem.IP.To4() == nil {
			continue
		}
		return elem, nil
	}
	return nil, errors.New("no IPv4 CIDRs found")
}

// getFirst4 returns the first IPv4 address from the list of IP addresses.
// If no IPv4 addresses are found, an error is raised.
func getFirst4(elems []net.IP) (net.IP, error) {
	for _, elem := range elems {
		if elem == nil || elem.To4() == nil {
			continue
		}
		return elem, nil
	}
	return nil, errors.New("no IPv4 address found")
}

// GetFirst4String returns the first IPv4 address from a list of IP address strings.
// If no IPv4 addresses are found, an error is raised.
func GetFirst4String(elems []string) (string, error) {
	ips := []net.IP{}
	for _, elem := range elems {
		for _, v := range strings.Split(elem, ",") {
			ips = append(ips, net.ParseIP(v))
		}
	}
	ip, err := getFirst4(ips)
	if err != nil {
		return "", err
	}
	return ip.String(), nil
}

View on GitHub (pinned to 6ba341e396)

Solutions

1. Include an IPv4 in the address list: --node-ip=192.0.2.10,2001:db8::10 (or set the IPv4 on the interface used for autodetection).
2. Ensure the node's primary interface has a global unicast IPv4 address when autodetection is used.
3. If the node is intentionally IPv6-only, use GetFirstString (v4-then-v6 fallback) or the v6-specific helpers instead of IPv4-requiring paths.

Example fix

# before: v6-only node-ip, IPv4 derivation fails
k3s server --node-ip=2001:db8::10

# after: dual-stack node-ip
k3s server --node-ip=192.0.2.10,2001:db8::10

// Equivalent of GetFirst4String pre-check
count := 0
for _, s := range strings.Split(nodeIPFlag, ",") {
    if ip := net.ParseIP(s); ip != nil && ip.To4() != nil {
        count++
    }
}
if count == 0 {
    return errors.New("no IPv4 in node-ip list")
}

if err != nil && strings.Contains(err.Error(), "no IPv4 address found") {
    // add an IPv4 to --node-ip or fix the interface, then restart
}

When it happens

Trigger: Passing an address list with only IPv6 entries to a code path that requires IPv4 - e.g. --node-ip set to a single v6 address on a component that derives an IPv4 service/bind address from it, or GetFirstString called where no v4 fallback is tolerated.

Common situations: IPv6-only hosts; --node-ip typo'd or partially set; interfaces lacking IPv4 during network reconfiguration; dual-stack flags missing their v4 member.

Related errors

• no IPv4 CIDRs found
• no IPv6 address found
• invalid node-ip: %w
• critical configuration value mismatch between servers
• unable to enable/disable secrets encryption, unknown configu

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/565af4b997784410. Report an issue: GitHub.