What causes "scroll offset must be a non-negative integer" in junegunn/fzf?

scroll offset must be a non-negative integer

Error message

scroll offset must be a non-negative integer

What it means

fzf requires --scroll-off (the number of lines kept above/below the cursor during vertical scrolling) to be zero or positive. Negative values are rejected by the post-parse check at options.go:3517.

Source

Thrown at src/options.go:3517

			}
		}

		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")
	}

	if opts.FreezeLeft < 0 || opts.FreezeRight < 0 {
		return errors.New("number of fields to freeze must be a non-negative integer")
	}

	if validateJumpLabels {
		for _, r := range opts.JumpLabels {
			if r < 32 || r > 126 {
				return errors.New("non-ascii jump labels are not allowed")

View on GitHub (pinned to bd4efa277b)

Solutions

Use a non-negative value
Clamp dynamic values with max(0, n)
Leave the option out to use the default

Example fix

# before
fzf --scroll-off=-3
# after
fzf --scroll-off=3

Defensive patterns

Strategy: validation

Validate before calling

// Shell: clamp scroll-off
so=$(( lines > 0 ? lines : 0 ))
exec fzf --scroll-off="$so"

Prevention

Clamp scroll-off arithmetic to 0
Omit the option when unsure (sane default exists)
Test layout scripts at tiny window sizes where computed values go negative

When it happens

Trigger: Passing --scroll-off=-1, or a script computing a negative scroll-off (e.g. from lines-in-view arithmetic). opts.ScrollOff < 0 triggers the error.

Common situations: Dynamic sizing scripts subtracting too much from viewport height; mistyping the value with a minus sign.

Related errors

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