kovidgoyal/kitty · error

Not a valid IP address: %#v. Cannot use: %s

Error message

Not a valid IP address: %#v. Cannot use: %s

What it means

For network types ip/ip4/ip6, ParseSocketAddress requires the address portion to parse as a bare IP address (validated via the ipaddress-go hostname parser's IsAddress). A hostname like 'localhost' or a malformed IP fails with this error.

Source

Thrown at tools/utils/sockets.go:37

	}
	if network == "unix" {
		if strings.HasPrefix(addr, "@") && runtime.GOOS != "linux" {
			err = fmt.Errorf("Abstract UNIX sockets are only supported on Linux. Cannot use: %s", spec)
		}
		return
	}

	if network == "tcp" || network == "tcp6" || network == "tcp4" {
		host := ipaddr.NewHostName(addr)
		if host.IsAddress() {
			network = "ip"
		}
		return
	}
	if network == "ip" || network == "ip6" || network == "ip4" {
		host := ipaddr.NewHostName(addr)
		if !host.IsAddress() {
			err = fmt.Errorf("Not a valid IP address: %#v. Cannot use: %s", addr, spec)
		}
		return
	}
	if network == "fd" {
		fd := -1
		if fd, err = strconv.Atoi(addr); err != nil || fd < 0 {
			err = fmt.Errorf("Not a valid file descriptor number: %#v. Cannot use: %s", addr, spec)
		}
		return
	}
	err = fmt.Errorf("Unknown network type: %#v in socket address: %s", network, spec)
	return
}

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use a literal IP: ip:127.0.0.1 or ip6:::1.
2. Use tcp:hostname:port if you need DNS resolution and ports.
3. If only a hostname is known, resolve it with net.LookupHost before building the spec.
4. Fix typos in the IP literal.

Example fix

// before
net, addr, err := utils.ParseSocketAddress("ip:localhost")
// after
net, addr, err := utils.ParseSocketAddress("tcp:localhost:8080")

_, addr, _ := strings.Cut(spec, ":")
if net.ParseIP(addr) == nil {
    return fmt.Errorf("%q is not an IP literal; use tcp: for hostnames", addr)
}

func isIPLiteral(s string) bool {
    return net.ParseIP(s) != nil
}

net, addr, err := utils.ParseSocketAddress(spec)
if err != nil && strings.Contains(err.Error(), "Not a valid IP address") {
    ips, _ := net.LookupHost(hostname)
    net, addr, err = utils.ParseSocketAddress("ip:" + ips[0])
}

When it happens

Trigger: Specs like ip:localhost, ip:999.1.1.1, or ip6:127.0.0.1 (wrong family) — note ip4/ip6 family mismatches may pass this check but fail later at dial time; this error is specifically for non-IP-literal addresses.

Common situations: Confusing the ip (raw IP, no port) network with tcp (host:port); using DNS names where a literal IP is required; copy-pasted addresses with typos.

Related errors

• Not a valid file descriptor number: %#v. Cannot use: %s
• Invalid socket address: %s must be prefix by a protocol such
• Abstract UNIX sockets are only supported on Linux. Cannot us
• Unknown network type: %#v in socket address: %s
• This should be run as kitten icat

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/d2310f1abf77c5e3. Report an issue: GitHub.