k3s-io/k3s · error

invalid node-ip: %w

Error message

invalid node-ip: %w

What it means

GetHostnameAndIPs(name, nodeIPs) parses the node IPs supplied via configuration (--node-ip style flags). When nodeIPs is non-empty it delegates to ParseStringSliceToIPs, which splits each element on commas and net.ParseIP's every token; the first unparseable token aborts with this wrapped 'invalid node-ip' error.

Source

Thrown at pkg/util/net.go:157

	ips := []net.IP{}
	if len(nodeIPs) == 0 {
		hostIP, err := apinet.ChooseHostInterface()
		if err != nil {
			return "", nil, err
		}
		ips = append(ips, hostIP)
		// If IPv6 it's an IPv6 only node
		if hostIP.To4() != nil {
			hostIPv6, err := apinet.ResolveBindAddress(net.IPv6loopback)
			if err == nil && !hostIPv6.Equal(hostIP) {
				ips = append(ips, hostIPv6)
			}
		}
	} else {
		var err error
		ips, err = ParseStringSliceToIPs(nodeIPs)
		if err != nil {
			return "", nil, fmt.Errorf("invalid node-ip: %w", err)
		}
	}

	if name == "" {
		hostname, err := os.Hostname()
		if err != nil {
			return "", nil, err
		}
		name = hostname
	}

	// Use lower case hostname to comply with kubernetes constraint:
	// https://github.com/kubernetes/kubernetes/issues/71140
	name = strings.ToLower(name)

	return name, ips, nil
}

View on GitHub (pinned to 6ba341e396)

Solutions

1. Check the exact node-ip list; every comma-separated token must be a literal IPv4/IPv6 address (no hostnames, no /prefix)
2. Remove trailing commas and empty items ('10.0.0.1,' to '10.0.0.1')
3. Validate at config-load time with util.ParseStringSliceToIPs (it is exported) before starting the node
4. Restart the agent/node after fixing so the config is re-read

Example fix

# before
--node-ip=10.42.0.1,
# after
--node-ip=10.42.0.1

// Validate at config-load time, before GetHostnameAndIPs runs.
if len(cfg.NodeIPs) > 0 {
	if _, err := util.ParseStringSliceToIPs(cfg.NodeIPs); err != nil {
		return fmt.Errorf("bad --node-ip: %w", err)
	}
}

name, ips, err := util.GetHostnameAndIPs(cfg.NodeName, cfg.NodeIPs)
if err != nil {
	if strings.Contains(err.Error(), "invalid node-ip") {
		// config problem, not environmental: fail fast with a clear message
		return fmt.Errorf("fix --node-ip in config: %w", err)
	}
	return err
}

When it happens

Trigger: Calling GetHostnameAndIPs with a node-ip list containing a malformed address ('10.0.0.256', '172.17.0', a hostname, a CIDR like '10.42.0.0/16') or an empty token produced by a trailing comma or ',,'.

Common situations: Config typos in CLI flags or cluster config files; trailing/double commas from templating or Helm values; users pasting DNS names or CIDRs where a literal IP is required.

Related errors

• invalid ip format '%s'
• no IPv4 CIDRs found
• no IPv4 address found
• no IPv6 address found
• ip: %v is not ipv4 or ipv6

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