junegunn/fzf · error

header lines must be a non-negative integer

Error message

header lines must be a non-negative integer

What it means

fzf validates that --headerlines is not negative after option parsing completes. HeaderLines counts lines taken from the top of the input to display as a sticky header, so a negative count is meaningless.

Source

Thrown at src/options.go:3509

			} else if match, _ := optString(arg, "-s"); match {
				opts.Sort = 1 // Don't care
			} else if match, value := optString(arg, "-m"); match {
				if opts.Multi, err = atoi(value); err != nil {
					return err
				}
			} else {
				return errors.New("unknown option: " + arg)
			}
		}

		if val != nil {
			return errors.New("unexpected value for " + arg + ": " + *val)
		}
	}
	*index += len(allArgs)

	if opts.HeaderLines < 0 {
		return errors.New("header lines must be a non-negative integer")
	}

	if opts.HscrollOff < 0 {
		return errors.New("hscroll offset must be a non-negative integer")
	}

	if opts.ScrollOff < 0 {
		return errors.New("scroll offset must be a non-negative integer")
	}

	if opts.Tabstop < 1 {
		return errors.New("tab stop must be a positive integer")
	}

	if len(opts.JumpLabels) == 0 {
		return errors.New("empty jump labels")
	}

View on GitHub (pinned to bd4efa277b)

Solutions

1. Fix the arithmetic so the value is 0 or positive
2. If the value is dynamic, clamp it: max(0, n)
3. Remember 0 means 'no header lines', not negative

Example fix

# before
fzf --headerlines=$(( count - 2 ))
# after
fzf --headerlines=$(( count > 2 ? count - 2 : 0 ))

// Shell: clamp header lines
hl=$(( n > 2 ? n - 2 : 0 ))
exec fzf --headerlines="$hl"

When it happens

Trigger: Passing --headerlines=-1 or a negative value computed by a script (e.g. --headerlines=$((n-2)) when n < 2). The post-parse check at options.go:3509 rejects opts.HeaderLines < 0.

Common situations: Shell arithmetic producing negative counts (empty files, off-by-one); reusing a header-lines value from another context where 0/negative meant 'auto'.

Related errors

• --header-border=inline requires --header-lines-border to be
• 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/78d88d9e8309e471. Report an issue: GitHub.