What causes "--scrollbar should be given one or two characters" in junegunn/fzf?

Provide exactly one character (used for both thumb and track) or two characters (thumb then track)

--scrollbar should be given one or two characters

Error message

--scrollbar should be given one or two characters

What it means

fzf's --scrollbar accepts exactly one character (uniform scrollbar) or two characters (separate thumb and track). The check at options.go:3635 rejects any value of more than two runes.

Source

Thrown at src/options.go:3635

			return err
		}
	}

	if opts.Marker != nil {
		if err := validateSign(*opts.Marker, "marker", 2); err != nil {
			return err
		}
	}

	if opts.Gutter != nil && uniseg.StringWidth(*opts.Gutter) != 1 ||
		opts.GutterRaw != nil && uniseg.StringWidth(*opts.GutterRaw) != 1 {
		return errors.New("gutter display width should be 1")
	}

	if opts.Scrollbar != nil {
		runes := []rune(*opts.Scrollbar)
		if len(runes) > 2 {
			return errors.New("--scrollbar should be given one or two characters")
		}
		for _, r := range runes {
			if uniseg.StringWidth(string(r)) != 1 {
				return errors.New("scrollbar display width should be 1")
			}
		}
	}

	if opts.Height.auto && (opts.Tmux == nil || opts.Tmux.index < opts.Height.index) {
		for _, s := range []sizeSpec{opts.Margin[0], opts.Margin[2]} {
			if s.percent {
				return errors.New("adaptive height is not compatible with top/bottom percent margin")
			}
		}
		for _, s := range []sizeSpec{opts.Padding[0], opts.Padding[2]} {
			if s.percent {
				return errors.New("adaptive height is not compatible with top/bottom percent padding")
			}

View on GitHub (pinned to bd4efa277b)

Solutions

Provide exactly one character (used for both thumb and track) or two characters (thumb then track)
Trim accidental spaces from the value
To disable the scrollbar, unset the option instead of padding it

Example fix

# before
fzf --scrollbar='=== '
# after
fzf --scrollbar='=·'

Defensive patterns

Strategy: validation

Validate before calling

// Go: enforce the one-or-two rune rule
runes := []rune(scrollbar)
if len(runes) > 2 { scrollbar = string(runes[:2]) }

Type guard

func validScrollbarLen(s string) bool { n := len([]rune(s)); return n >= 1 && n <= 2 }

Prevention

Remember the two-character form is thumb+track, not a repeating pattern
Trim whitespace from configured scrollbar strings
Use one character when thumb and track should look identical

When it happens

Trigger: Passing --scrollbar with three or more characters, e.g. --scrollbar='::' is fine but --scrollbar=':::' or --scrollbar=' - ' triggers len(runes) > 2.

Common situations: Trying to build a multi-segment scrollbar from ASCII art; copy-pasting strings with surrounding spaces; misunderstanding the two-character form as thumb+track rather than a pattern.

Related errors

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