kovidgoyal/kitty · error · ValueError

The value {val} is not a valid choice for scrollbar

Error message

The value {val} is not a valid choice for scrollbar

What it means

The scrollbar option in kitty.conf only accepts: scrolled, always, never, hovered, scrolled-and-hovered, scrolled-or-hovered. The parser lowercases the value and raises ValueError on anything else. Newer scrollbar modes (hovered variants) only exist in recent kitty versions.

Source

Thrown at kitty/options/parse.py:1282

    def resize_in_steps(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['resize_in_steps'] = to_bool(val)

    def scrollback_fill_enlarged_window(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['scrollback_fill_enlarged_window'] = to_bool(val)

    def scrollback_lines(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['scrollback_lines'] = scrollback_lines(val)

    def scrollback_pager(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['scrollback_pager'] = to_cmdline(val)

    def scrollback_pager_history_size(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['scrollback_pager_history_size'] = scrollback_pager_history_size(val)

    def scrollbar(self, val: str, ans: dict[str, typing.Any]) -> None:
        val = val.lower()
        if val not in self.choices_for_scrollbar:
            raise ValueError(f"The value {val} is not a valid choice for scrollbar")
        ans["scrollbar"] = val

    choices_for_scrollbar = frozenset(('scrolled', 'always', 'never', 'hovered', 'scrolled-and-hovered', 'scrolled-or-hovered'))

    def scrollbar_gap(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['scrollbar_gap'] = positive_float(val)

    def scrollbar_handle_color(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['scrollbar_handle_color'] = scrollbar_color(val)

    def scrollbar_handle_opacity(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['scrollbar_handle_opacity'] = positive_float(val)

    def scrollbar_hitbox_expansion(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['scrollbar_hitbox_expansion'] = positive_float(val)

    def scrollbar_hover_width(self, val: str, ans: dict[str, typing.Any]) -> None:
        ans['scrollbar_hover_width'] = positive_float(val)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use one of: scrolled, always, never, hovered, scrolled-and-hovered, scrolled-or-hovered
2. If `hovered` is rejected, upgrade kitty to a version that supports hover-based scrollbars
3. Verify no trailing spaces or quotes around the value in kitty.conf

Example fix

# before
scrollbar auto
# after
scrollbar always

value = value.lower()
if value not in ('scrolled','always','never','hovered','scrolled-and-hovered','scrolled-or-hovered'):
    raise SystemExit(f'bad scrollbar: {value}')

def is_scrollbar(v: str) -> bool:
    return v.lower() in ('scrolled','always','never','hovered','scrolled-and-hovered','scrolled-or-hovered')

When it happens

Trigger: Setting `scrollbar` to a string outside the allowed set, e.g. `scrollbar auto`, `scrollbar on/off`, or using `hovered` on a kitty version older than the one that introduced it.

Common situations: Migrating from other terminals that use on/off/auto semantics; running an older kitty binary against a config written for a newer release.

Related errors

• The value {x} is not a known choice
• The value {val} is not a valid choice for progress_bar
• The value {val} is not a valid choice for strip_trailing_spa
• The value {val} is not a valid choice for tab_bar_align
• The value {val} is not a valid choice for tab_bar_style

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/c5e40174251d2e99. Report an issue: GitHub.