kovidgoyal/kitty · error · ValueError

must have codepoints AND font name

Error message

must have codepoints AND font name

What it means

symbol_map parser requires at least min_size (default 2) whitespace-separated parts: codepoint spec(s) plus a font family name. With fewer parts it cannot form a mapping and raises.

Source

Thrown at kitty/options/utils.py:1220

        raise ValueError(f'Invalid paste actions: {q - s}, ignoring')
    return q


def action_alias(val: str) -> Iterable[tuple[str, str]]:
    parts = val.split(maxsplit=1)
    if len(parts) > 1:
        alias_name, rest = parts
        yield alias_name, rest


kitten_alias = action_alias


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)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Append the symbol font family after the codepoints
2. Verify the whole symbol_map line wasn't cut off

Example fix

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

def valid_symbol_map(v: str) -> bool:
    return len(v.split()) >= 2

When it happens

Trigger: A symbol_map line with only codepoints and no font name, e.g. 'symbol_map U+E0A0' or an empty value.

Common situations: Truncated config line, missing font argument when editing kitty.conf, or wrong min_size when calling symbol_map_parser programmatically.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

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