junegunn/fzf · error

--threads must be a positive integer

Error message

--threads must be a positive integer

What it means

Thrown when --threads parses to a negative number. Despite the wording 'positive integer', the check is opts.Threads < 0, so 0 is accepted (0 means auto/default thread count) and any negative value is rejected. A non-numeric value fails earlier in nextInt with 'number of threads required'.

Source

Thrown at src/options.go:3450

			if opts.WalkerOpts, err = parseWalkerOpts(str); err != nil {
				return err
			}
		case "--walker-root":
			if opts.WalkerRoot, err = nextDirs(); err != nil {
				return err
			}
		case "--walker-skip":
			str, err := nextString("directory names to ignore required")
			if err != nil {
				return err
			}
			opts.WalkerSkip = filterNonEmpty(strings.Split(str, ","))
		case "--threads":
			if opts.Threads, err = nextInt("number of threads required"); err != nil {
				return err
			}
			if opts.Threads < 0 {
				return errors.New("--threads must be a positive integer")
			}
		case "--bench":
			str, err := nextString("duration required (e.g. 3s, 500ms)")
			if err != nil {
				return err
			}
			dur, err := time.ParseDuration(str)
			if err != nil {
				return errors.New("invalid duration for --bench: " + str)
			}
			opts.Bench = dur
		case "--profile-cpu":
			if opts.CPUProfile, err = nextString("file path required: cpu"); err != nil {
				return err
			}
		case "--profile-mem":
			if opts.MEMProfile, err = nextString("file path required: mem"); err != nil {
				return err

View on GitHub (pinned to bd4efa277b)

Solutions

1. Use 0 for automatic thread count, or a positive integer
2. Clamp computed values: [ "$N" -lt 0 ] && N=0
3. If you wanted 'auto', just omit --threads entirely

Example fix

# before
fzf --threads "$(($(nproc)/2-2))"
# after
N=$(($(nproc)/2-2)); [ "$N" -lt 0 ] && N=0
fzf --threads "$N"

# bash: 0 = auto, negatives rejected
N="${THREADS:-0}"
[[ "$N" =~ ^[0-9]+$ ]] || { echo "--threads must be numeric" >&2; exit 1; }
fzf --threads "$N"

threads_ok() { [[ "$1" =~ ^[0-9]+$ ]]; }

When it happens

Trigger: `--threads -4`, or `--threads "$N"` where N underflows to negative in shell arithmetic.

Common situations: Computing thread counts from CPU/2 style expressions on single-CPU containers producing 0 or negative results (0 passes, negatives do not); attempting -1 as a sentinel for 'automatic' — use 0 instead.

Related errors

• number of items to keep must be a positive integer
• unknown action: ${spec}
• invalid layout (expected: default / reverse / reverse-list)
• invalid info style (expected: default|right|hidden|inline[-r
• history max must be a positive integer

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