{"record":{"id":"9697a2e650d0ccce","repo":"junegunn/fzf","slug":"gutter-display-width-should-be-1","errorCode":null,"errorMessage":"gutter display width should be 1","messagePattern":"gutter display width should be 1","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/options.go","lineNumber":3629,"sourceCode":"\treturn nil\n}\n\nfunc validateOptions(opts *Options) error {\n\tif opts.Pointer != nil {\n\t\tif err := validateSign(*opts.Pointer, \"pointer\", 2); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\tif opts.Marker != nil {\n\t\tif err := validateSign(*opts.Marker, \"marker\", 2); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\tif opts.Gutter != nil && uniseg.StringWidth(*opts.Gutter) != 1 ||\n\t\topts.GutterRaw != nil && uniseg.StringWidth(*opts.GutterRaw) != 1 {\n\t\treturn errors.New(\"gutter display width should be 1\")\n\t}\n\n\tif opts.Scrollbar != nil {\n\t\trunes := []rune(*opts.Scrollbar)\n\t\tif len(runes) > 2 {\n\t\t\treturn errors.New(\"--scrollbar should be given one or two characters\")\n\t\t}\n\t\tfor _, r := range runes {\n\t\t\tif uniseg.StringWidth(string(r)) != 1 {\n\t\t\t\treturn errors.New(\"scrollbar display width should be 1\")\n\t\t\t}\n\t\t}\n\t}\n\n\tif opts.Height.auto && (opts.Tmux == nil || opts.Tmux.index < opts.Height.index) {\n\t\tfor _, s := range []sizeSpec{opts.Margin[0], opts.Margin[2]} {\n\t\t\tif s.percent {\n\t\t\t\treturn errors.New(\"adaptive height is not compatible with top/bottom percent margin\")","sourceCodeStart":3611,"sourceCodeEnd":3647,"githubUrl":"https://github.com/junegunn/fzf/blob/bd4efa277b49ef34ca4025bff9b1a288e1980eff/src/options.go#L3611-L3647","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nfzf --gutter='||'\n# after\nfzf --gutter='|'","handlingStrategy":"type-guard","validationCode":"// Go: check gutter width with the same measure fzf uses\nimport \"github.com/rivo/uniseg\"\nfunc validGutter(s string) bool { return uniseg.StringWidth(s) == 1 }","typeGuard":"func isSingleWidth(s string) bool { return uniseg.StringWidth(s) == 1 }","tryCatchPattern":null,"preventionTips":["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"],"tags":["fzf","cli","validation","unicode","gutter"],"backgroundTag":null,"analyzedSha":"bd4efa277b49ef34ca4025bff9b1a288e1980eff","analyzedAt":"2026-08-15T06:11:46.983Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}