kovidgoyal/kitty · error · ValueError

Invalid range: {a:x} - {b:x}

Error message

Invalid range: {a:x} - {b:x}

What it means

After parsing codepoints, kitty validates each range: the end must not be below the start, values must be within 1..sys.maxunicode. Violations raise this error showing the hex values.

Source

Thrown at kitty/options/utils.py:1233

def symbol_map_parser(val: str, min_size: int = 2) -> Iterable[tuple[tuple[int, int], str]]:
    parts = val.split()

    if len(parts) < min_size:
        raise ValueError('must have codepoints AND font name')
    family = ' '.join(parts[1:])

    def to_chr(x: str) -> int:
        if not x.startswith('U+'):
            raise ValueError(f'{x} is not a unicode codepoint of the form U+number')
        return int(x[2:], 16)

    for x in parts[0].split(','):
        a_, b_ = x.replace('–', '-').partition('-')[::2]
        b_ = b_ or a_
        a, b = map(to_chr, (a_, b_))
        if b < a or max(a, b) > sys.maxunicode or min(a, b) < 1:
            raise ValueError(f'Invalid range: {a:x} - {b:x}')
        yield (a, b), family


def symbol_map(val: str) -> Iterable[tuple[tuple[int, int], str]]:
    yield from symbol_map_parser(val)


def narrow_symbols(val: str) -> Iterable[tuple[tuple[int, int], int]]:
    for x, y in symbol_map_parser(val, min_size=1):
        yield x, int(y or 1)


def parse_key_action(action: str, action_type: MapType = MapType.MAP) -> KeyAction:
    parts = action.strip().split(maxsplit=1)
    func = parts[0]
    if len(parts) == 1:
        return KeyAction(func, ())
    rest = parts[1]

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Ensure range start <= end
2. Keep values between U+1 and U+10FFFF

Example fix

# before
symbol_map U+E0A2-U+E0A0 Nerd Font
# after
symbol_map U+E0A0-U+E0A2 Nerd Font

import sys
def valid_range(a: int, b: int) -> bool:
    return a <= b and 1 <= max(a, b) <= sys.maxunicode

When it happens

Trigger: Ranges like U+E0A2-U+E0A0 (reversed), U+0 (below 1), or values above U+10FFFF.

Common situations: Reversed range endpoints when hand-editing, or accidentally using codepoints beyond Unicode's maximum.

Related errors

• {x} is not a unicode codepoint of the form U+number
• This should be run as kitten broadcast
• Invalid panel options specified: {e}
• No option named: {k}
• No custom kitten named {kitten} found

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