kovidgoyal/kitty · error · KeyError

The map option {x} is unknown. Allowed options: {", ".join(a

Error message

The map option {x} is unknown. Allowed options: {", ".join(allowed_key_map_options)}

What it means

While parsing --options inside a map line, kitty checks each flag name (after replacing '-' with '_') against allowed_key_map_options; unknown flags raise KeyError listing the allowed set.

Source

Thrown at kitty/options/utils.py:1529

key_map_option_converters['allow_fallback'] = _convert_allow_fallback


def parse_options_for_map(val: str) -> tuple[KeyMapOptions, str]:
    expecting_arg = ''
    ans = KeyMapOptions()
    s = Shlex(val)
    while (tok := s.next_word())[0] > -1:
        x = tok[1]
        if expecting_arg:
            object.__setattr__(ans, expecting_arg, key_map_option_converters[expecting_arg](x))
            expecting_arg = ''
        elif x.startswith('--'):
            expecting_arg = x[2:]
            k, sep, v = expecting_arg.partition('=')
            k = k.replace('-', '_')
            expecting_arg = k
            if expecting_arg not in allowed_key_map_options:
                raise KeyError(f'The map option {x} is unknown. Allowed options: {", ".join(allowed_key_map_options)}')
            if sep == '=':
                object.__setattr__(ans, k, key_map_option_converters[k](v))
                expecting_arg = ''
        else:
            return ans, val[tok[0] :]
    return ans, ''


def parse_map(val: str) -> Iterable[KeyDefinition]:
    parts = val.split(maxsplit=1)
    options = default_key_map_options
    if len(parts) == 2:
        sc, action = parts
        if sc.startswith('--'):
            options, leftover = parse_options_for_map(val)
            parts = leftover.split(maxsplit=1)
            if len(parts) == 1:
                sc, action = parts[0], ''

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use only the allowed map options shown in the error message (e.g. mapped, launched, allow-fallback, etc.)
2. Fix typos; use dashes or underscores consistently (they are normalized)
3. Check kitty docs for key map options in your version

Example fix

# before
map --hide-from-cat f1 copy_to_clipboard
# after
map --mapped f1 copy_to_clipboard

from kitty.options.utils import allowed_key_map_options
def valid_map_option(flag: str) -> bool:
    return flag.lstrip('-').replace('-', '_') in allowed_key_map_options

def is_valid_map_option(flag: str, allowed: set[str]) -> bool:
    return flag.lstrip('-').replace('-', '_') in allowed

When it happens

Trigger: A map line like 'map --hidden f1 ...' where 'hidden' is not an allowed key map option; also '--some-opt=value' with a misspelled key.

Common situations: Typos in map options, using scrollbar/theme options that only apply elsewhere, or version drift where an option was renamed.

Related errors

• Unknown action: {func}
• allow_fallback values must be a subset of shifted, ascii, go
• Unknown map option: %s
• This should be run as kitten broadcast
• unknown option -- {arg[1:]}

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