kovidgoyal/kitty · error · ValueError

The value {x} is not a known choice

Error message

The value {x} is not a known choice

What it means

Choice.__call__ (from choices()) lowercases the input and raises ValueError if it is not among the declared choices — the standard parser for enum-like kitty config options.

Source

Thrown at kitty/conf/utils.py:142

def python_string(text: str) -> str:
    from ast import literal_eval

    text = (text[:-1] + "\\'") if text.endswith("'") else text
    ans: str = literal_eval("'''" + text.replace("'''", "'\\''") + "'''")
    return ans


class Choice:
    def __init__(self, choices: Sequence[str]):
        self.defval = choices[0]
        self.all_choices = frozenset(choices)

    def __call__(self, x: str) -> str:
        x = x.lower()
        if x not in self.all_choices:
            raise ValueError(f'The value {x} is not a known choice')
        return x


def choices(*choices: str) -> Choice:
    return Choice(choices)


class CurrentlyParsing:
    __slots__ = 'line', 'number', 'file'

    def __init__(self, line: str = '', number: int = -1, file: str = ''):
        self.line = line
        self.number = number
        self.file = file

    def __copy__(self) -> 'CurrentlyParsing':
        return CurrentlyParsing(self.line, self.number, self.file)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the option's documented choices and fix the spelling
2. Upgrade/downgrade kitty to match the available choices
3. Remember matching is case-insensitive, so case is not the issue

Example fix

# before
background_tint none-x
# after
background_tint no

allowed = set(choice_parser.all_choices)
if value.lower() not in allowed:
    value = choice_parser.defval

def is_valid_choice(choice: Choice, x: str) -> bool:
    return x.lower() in choice.all_choices

try:
    v = choice_parser(x)
except ValueError:
    v = choice_parser.defval

When it happens

Trigger: Setting a choice-based config option (e.g. a strategy/mode enum) to a value not in the parser's choice set; note comparison is case-insensitive after lowercasing.

Common situations: Misspelled enum values in kitty.conf, or values valid only in newer/older kitty versions.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• 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
• 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/8eaf8e8a4945e005. Report an issue: GitHub.