What causes "not a valid integer: ${str}" in junegunn/fzf?

Re-run fzf: a one-off kernel/runtime hiccup is the only plausible transient cause.

not a valid integer: ${str}

Error message

not a valid integer: ${str}

What it means

Returned by startHttpServer (src/server.go:115) when fzf is started with --listen 0 (ephemeral port) and the kernel-assigned address returned by listener.Addr().String() cannot be split on ':' to recover the actual port number. Because Go's net.TCPAddr.String() always renders as 'host:port' (even for IPv6 as '[::]:port'), a string with zero ':' parts is essentially unreachable; this is a defensive guard against unexpected Addr implementations or kernel oddities.

Source

Thrown at src/options.go:827

		Unsafe:       false,
		ClearOnExit:  true,
		WalkerOpts:   walkerOpts{file: true, hidden: true, follow: true},
		WalkerRoot:   []string{"."},
		WalkerSkip:   []string{".git", "node_modules"},
		TtyDefault:   tui.DefaultTtyDevice,
		Help:         false,
		Version:      false}
}

func isDir(path string) bool {
	stat, err := os.Stat(path)
	return err == nil && stat.IsDir()
}

func atoi(str string) (int, error) {
	num, err := strconv.Atoi(str)
	if err != nil {
		return 0, errors.New("not a valid integer: " + str)
	}
	return num, nil
}

func atof(str string) (float64, error) {
	num, err := strconv.ParseFloat(str, 64)
	if err != nil {
		return 0, errors.New("not a valid number: " + str)
	}
	return num, nil
}

func splitNth(str string) ([]Range, error) {
	if match, _ := regexp.MatchString("^[0-9,-.]+$", str); !match {
		return nil, errors.New("invalid format: " + str)
	}

	tokens := strings.Split(str, ",")

View on GitHub (pinned to bd4efa277b)

Solutions

Re-run fzf: a one-off kernel/runtime hiccup is the only plausible transient cause.
Stop using --listen 0 and pass an explicit free port (e.g. --listen 6266) so the port-extraction path is skipped entirely.
Check the Go version / report a bug to the fzf repo if this reproduces, including OS, Go version, and the address string printed in the message.
If wrapping fzf in tests with fake listeners, ensure the fake Addr() returns a valid 'host:port' TCP address.

Example fix

# before
fzf --listen 0   # (defensive path; error practically unreachable)

# after
fzf --listen 6266   # explicit port bypasses port extraction entirely

Defensive patterns

Strategy: try-catch

Validate before calling

// Practically unreachable; if wrapping fzf, simply avoid --listen 0
// and pass an explicit port so this code path is never exercised:
//   fzf --listen 6266   (instead of: fzf --listen 0)
null

Type guard

func isPortExtractFailure(stderr string) bool {
    return strings.Contains(stderr, "cannot extract port: ")
}

Try / catch

// treat as a transient/defensive failure: retry once, then fall back to a fixed port
if err != nil && strings.Contains(stderr, "cannot extract port") {
    retryOnceWith("--listen", "6266")
}

Prevention

Use explicit --listen ports in scripted/frozen environments.
Pin a known-good fzf and Go version in containers to avoid netstack surprises.
Report reproductions upstream with the printed address string.

When it happens

Trigger: Requires --listen 0 (port 0) AND listener.Addr().String() containing no ':' character. No standard Linux/macOS/Windows TCP listener produces such a string, so in practice this error is never observed from normal fzf usage; it exists as a sanity check in the port-extraction path (src/server.go:111-116).

Common situations: Not reproducible in real deployments. Theoretically conceivable with an exotic Go runtime patch, a custom netstack, or a future refactor changing how the listener address is obtained (e.g. switching to a listener type whose Addr() is a non-TCP Addr). Users seeing this message should suspect a heavily modified environment rather than configuration.

Related errors

AI-assisted analysis of junegunn/fzf@bd4efa277b (2026-08-15). Data as JSON: /api/errors/c4ea198a19ede63c. Report an issue: GitHub.