kovidgoyal/kitty · error · KeyError

Invalid value for {self._name}: {value!r}

Error message

Invalid value for {self._name}: {value!r}

What it means

A LiteralField/enum-style option descriptor validates that the assigned string is one of its allowed literal values; anything else raises KeyError naming the option and offending value.

Source

Thrown at kitty/options/utils.py:1400

class LiteralField(Generic[T]):
    def __init__(self, vals: tuple[T, ...]):
        self._vals = vals

    def __set_name__(self, owner: object, name: str) -> None:
        self._name = name

    def __get__(self, obj: object, type: type | None = None) -> T:
        if obj is None:
            return self._vals[0]
        val = obj.__dict__.get(self._name)
        if val is None or isinstance(val, LiteralField):
            return self._vals[0]
        return cast(T, val)

    def __set__(self, obj: object, value: str) -> None:
        if value not in self._vals:
            raise KeyError(f'Invalid value for {self._name}: {value!r}')
        obj.__dict__[self._name] = value


OnUnknown = Literal['beep', 'end', 'ignore', 'passthrough']
OnAction = Literal['keep', 'end']


class KeyFallbackType(enum.Enum):
    shifted = 'shifted'
    alternate = 'alternate'

    def __repr__(self) -> str:
        return f'KeyFallbackType.{self.value}'


@dataclass(frozen=True)
class KeyMapOptions:
    when_focus_on: str = ''

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use one of the exact allowed values listed for the option
2. Match case exactly (values are case-sensitive)
3. Consult the option's docs for the accepted literals

Example fix

# before
notify_on_cmd_beep Warn
# after
notify_on_cmd_beep ignore

def valid_literal(field_vals: tuple[str, ...], v: str) -> bool:
    return v in field_vals

def is_valid_literal(v: str, allowed: tuple[str, ...]) -> bool:
    return v in allowed

When it happens

Trigger: Assigning a value outside the option's literal set, e.g. setting a 'beep|end|ignore|passthrough'-style option to 'warn', or case mismatches like 'Beep'.

Common situations: Misspelled or case-sensitive enum values in kitty.conf, values valid only in other kitty versions, or programmatic assignment bypassing normalization.

Related errors

• The value {x} is not a known choice
• {jt} is not a valid jump type for a linear easing function
• {first} is not a valid pointer shape name
• This should be run as kitten broadcast
• No option named: {k}

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