junegunn/fzf · error

scrollbar display width should be 1

Error message

scrollbar display width should be 1

What it means

Each character of --scrollbar must be exactly one terminal column wide, because the scrollbar occupies a single column on the right edge. After the length check, options.go:3639 loops over the runes and rejects any whose uniseg.StringWidth != 1.

Source

Thrown at src/options.go:3639

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

	if opts.Theme.Nth.IsColorDefined() {

View on GitHub (pinned to bd4efa277b)

Solutions

1. Restrict scrollbar characters to half-width glyphs (block elements like '█' and '·' are width 1)
2. Pick a different glyph if the current one renders wide in your font
3. Verify each candidate rune's width programmatically before configuring

Example fix

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

// Go: every scrollbar rune must be exactly one column wide
func validScrollbarWidths(s string) bool {
    for _, r := range s {
        if uniseg.StringWidth(string(r)) != 1 { return false }
    }
    return true
}

func allRunesWidthOne(s string) bool {
    for _, r := range s {
        if uniseg.StringWidth(string(r)) != 1 { return false }
    }
    return true
}

When it happens

Trigger: Using CJK ideographs, full-width forms, or emoji as scrollbar characters: --scrollbar='█·' is fine (both width 1) but --scrollbar='一' or --scrollbar='👍' fails since those runes are width 2.

Common situations: Aesthetic customization with box-drawing or Unicode art that includes a wide glyph; terminals/fonts rendering some glyphs as double width; combining characters with zero width.

Related errors

• gutter display width should be 1
• --scrollbar should be given one or two characters
• unknown action: ${spec}
• invalid layout (expected: default / reverse / reverse-list)
• invalid info style (expected: default|right|hidden|inline[-r

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