kovidgoyal/kitty · error · ValueError

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

Error message

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

What it means

underline_hyperlinks controls when hyperlinks are underlined and accepts hover, always, or never. The parser lowercases the value and raises ValueError for anything outside that set.

Source

Thrown at kitty/options/parse.py:1485

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

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

    choices_for_undercurl_style = frozenset(('thin-sparse', 'thin-dense', 'thick-sparse', 'thick-dense'))

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

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

    choices_for_underline_hyperlinks = frozenset(('hover', 'always', 'never'))

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

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

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

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

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

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use one of: hover, always, never
2. Replace boolean-style values: 'yes'→'always', 'no'→'never'
3. Check spelling after lowercasing

Example fix

# before
underline_hyperlinks yes
# after
underline_hyperlinks always

value = value.lower()
if value not in ('hover','always','never'):
    raise SystemExit(f'bad underline_hyperlinks: {value}')

def is_underline_hyperlinks(v: str) -> bool:
    return v.lower() in ('hover','always','never')

When it happens

Trigger: Setting `underline_hyperlinks yes`, `underline_hyperlinks on-hover`, or a typo like `allways` in kitty.conf or via remote option setting.

Common situations: Assuming boolean semantics (yes/no) like other kitty options; writing 'on-hover' instead of 'hover'; typos.

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

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