What causes "Not a valid file descriptor number: %#v. Cannot use: %s" in kovidgoyal/kitty?

Use a plain non-negative integer: fd:3.

Not a valid file descriptor number: %#v. Cannot use: %s

Error message

Not a valid file descriptor number: %#v. Cannot use: %s

What it means

For network type fd:, ParseSocketAddress expects the address to be a non-negative integer file descriptor number (for socket-activation style listening on an inherited fd). If Atoi fails or the fd is negative, this error is returned.

Source

Thrown at tools/utils/sockets.go:44

	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

Use a plain non-negative integer: fd:3.
Substitute the real fd number from the socket-activation environment (e.g. LISTEN_FDS_START + n).
Validate with strconv.Atoi and >= 0 before building the spec.
If you meant a path or TCP socket, use unix:/tcp: specs instead.

Example fix

// before
net, addr, err := utils.ParseSocketAddress("fd:${FD}") // FD unset
// after
net, addr, err := utils.ParseSocketAddress(fmt.Sprintf("fd:%d", fdNum))

Defensive patterns

Strategy: validation

Validate before calling

_, addr, _ := strings.Cut(spec, ":")
if n, err := strconv.Atoi(addr); err != nil || n < 0 {
    return fmt.Errorf("fd spec must be a non-negative integer, got %q", addr)
}

Type guard

func isNonNegInt(s string) bool {
    n, err := strconv.Atoi(s)
    return err == nil && n >= 0
}

Try / catch

net, addr, err := utils.ParseSocketAddress(spec)
if err != nil && strings.Contains(err.Error(), "file descriptor") {
    spec = fmt.Sprintf("fd:%d", fdNum)
    net, addr, err = utils.ParseSocketAddress(spec)
}

Prevention

Substitute real fd numbers from socket-activation env (LISTEN_FDS).
Validate fd specs with Atoi before startup.
Never leave fd placeholders like ${FD} unfilled.

When it happens

Trigger: Specs like fd:abc, fd:-1, fd: (empty), or fd:3.5. Also fd: with whitespace or a 0x-prefixed value.

Common situations: Socket-activation configs where the fd number placeholder was never substituted; hand-written configs with typos; fd indexes passed as strings from env vars.

Related errors

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