What causes "number of items to keep must be a positive integer" in junegunn/fzf?

Use --no-tail to disable tailing instead of --tail 0

number of items to keep must be a positive integer

Error message

number of items to keep must be a positive integer

What it means

Thrown when --tail receives a value <= 0. --tail keeps only the last N items of the input for a fast initial listing; 0 or negative values are meaningless (use --no-tail to disable tailing) and are rejected after the integer itself parsed successfully.

Source

Thrown at src/options.go:2881

			str, err := nextString("nth expression required")
			if err != nil {
				return err
			}
			if opts.IdNth, err = splitNth(str); err != nil {
				return err
			}
		case "--no-id-nth":
			opts.IdNth = nil
		case "--tac":
			opts.Tac = true
		case "--no-tac":
			opts.Tac = false
		case "--tail":
			if opts.Tail, err = nextInt("number of items to keep required"); err != nil {
				return err
			}
			if opts.Tail <= 0 {
				return errors.New("number of items to keep must be a positive integer")
			}
		case "--no-tail":
			opts.Tail = 0
		case "--smart-case":
			opts.Case = CaseSmart
		case "-i", "--ignore-case":
			opts.Case = CaseIgnore
		case "+i", "--no-ignore-case":
			opts.Case = CaseRespect
		case "-m", "--multi":
			if opts.Multi, err = optionalNumeric(maxMulti); err != nil {
				return err
			}
		case "+m", "--no-multi":
			opts.Multi = 0
		case "--ansi":
			opts.Ansi = true
		case "--no-ansi":

View on GitHub (pinned to bd4efa277b)

Solutions

Use --no-tail to disable tailing instead of --tail 0
Clamp computed values: N=$((LINES)); [ "$N" -lt 1 ] && N=1
Pass a positive count: `--tail 1000`

Example fix

# before
fzf --tail "$((LINES-100))"
# after
N=$((LINES-100)); [ "$N" -lt 1 ] && N=1
fzf --tail "$N"

Defensive patterns

Strategy: validation

Validate before calling

# bash
TAIL_N="${TAIL_N:-0}"
if [ "$TAIL_N" -gt 0 ] 2>/dev/null; then TAIL=(--tail "$TAIL_N"); else TAIL=(--no-tail); fi
fzf "${TAIL[@]}"

Type guard

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

Prevention

Use --no-tail to disable tailing, never --tail 0
Clamp computed tail counts to at least 1

When it happens

Trigger: `--tail 0`, `--tail -5`, or `--tail "$(($LINES-100))"` computing to <= 0 on small inputs/terminals.

Common situations: Dynamic tail sizing from terminal height or input length (wc -l) that underflows; users writing --tail 0 expecting to mean 'no tail' instead of --no-tail.

Related errors

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