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

Use a non-negative value (default is 10)

hscroll offset must be a non-negative integer

Error message

hscroll offset must be a non-negative integer

What it means

fzf requires --hscroll-off (the number of columns kept visible when horizontally scrolling a long line) to be zero or positive. A negative offset cannot keep anything visible, so it is rejected after parsing.

Source

Thrown at src/options.go:3513

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

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

View on GitHub (pinned to bd4efa277b)

Solutions

Use a non-negative value (default is 10)
Clamp computed values to 0
Omit the option to accept the default

Example fix

# before
fzf --hscroll-off=-5
# after
fzf --hscroll-off=5

Defensive patterns

Strategy: validation

Validate before calling

// Shell: clamp hscroll-off
hso=$(( off > 0 ? off : 0 ))
exec fzf --hscroll-off="$hso"

Prevention

Clamp computed offsets to 0
Remember the default is 10; usually you can omit the flag
Never pass values derived from width arithmetic without a floor

When it happens

Trigger: Passing --hscroll-off=-1 explicitly, or a computed negative value. The check at options.go:3513 fires when opts.HscrollOff < 0 after all args are consumed.

Common situations: Scripts deriving the offset from terminal width minus content width, which can go negative for very narrow terminals; typos with a leading dash.

Related errors

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