kovidgoyal/kitty · error · ValueError

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

Error message

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

What it means

window_title_bar positions the macOS/optional title bar and accepts only top or bottom. The parser lowercases and validates; other values raise ValueError during config parsing.

Source

Thrown at kitty/options/parse.py:1571

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

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

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

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

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

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

    choices_for_window_title_bar = frozenset(('top', 'bottom'))

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

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

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

    choices_for_window_title_bar_align = frozenset(('left', 'center', 'right'))

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use top or bottom
2. To hide the title bar use the appropriate decoration options for your OS instead of this option
3. Fix typos — only the two vertical positions are valid

Example fix

# before
window_title_bar hidden
# after
window_title_bar top

value = value.lower()
if value not in ('top','bottom'):
    raise SystemExit(f'bad window_title_bar: {value}')

def is_window_title_bar(v: str) -> bool:
    return v.lower() in ('top','bottom')

When it happens

Trigger: Setting `window_title_bar hidden`, `window_title_bar left`, or `window_title_bar up` in kitty.conf.

Common situations: Trying to hide the title bar with 'hidden' (hiding is done differently, e.g. macos_titlebar_color or hide_window decorations options); typos; non-macOS users setting an macOS-only option with guessed values.

Related errors

• The value {val} is not a valid choice for window_title_bar_a
• 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 scrollbar
• The value {val} is not a valid choice for strip_trailing_spa

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