What causes "gutter display width should be 1" in junegunn/fzf?

Use a single half-width character such as '|' or '┃' (verify width 1)

gutter display width should be 1

Error message

gutter display width should be 1

What it means

fzf requires that the --gutter (or --gutter-raw) string occupy exactly one terminal column, since the gutter is drawn as a single-column vertical strip next to each row. The check at options.go:3629 uses uniseg.StringWidth and rejects anything whose display width differs from 1.

Source

Thrown at src/options.go:3629

	return nil
}

func validateOptions(opts *Options) error {
	if opts.Pointer != nil {
		if err := validateSign(*opts.Pointer, "pointer", 2); err != nil {
			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")

View on GitHub (pinned to bd4efa277b)

Solutions

Use a single half-width character such as '|' or '┃' (verify width 1)
To disable the gutter, omit the option rather than passing an empty string
Test candidate glyphs with a width-aware function before configuring

Example fix

# before
fzf --gutter='||'
# after
fzf --gutter='|'

Defensive patterns

Strategy: type-guard

Validate before calling

// Go: check gutter width with the same measure fzf uses
import "github.com/rivo/uniseg"
func validGutter(s string) bool { return uniseg.StringWidth(s) == 1 }

Type guard

func isSingleWidth(s string) bool { return uniseg.StringWidth(s) == 1 }

Prevention

Use a known half-width glyph such as '|' or '┃'
To remove the gutter, unset --gutter rather than passing ''
Test custom glyphs with a width library — visual width in your font can differ from terminal width

When it happens

Trigger: Passing --gutter with an empty string, a two-character string, a zero-width character, or a double-width CJK/emoji character: uniseg.StringWidth(*opts.Gutter) != 1 triggers the error.

Common situations: Trying to use decorative multi-character gutters; using full-width characters (e.g. '｜' U+FF5C) instead of ASCII '|'; passing an empty string to 'disable' the gutter instead of unsetting the option.

Related errors

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