{"record":{"id":"a037778f013c00cd","repo":"kovidgoyal/kitty","slug":"the-map-option-x-is-unknown-allowed-options","errorCode":null,"errorMessage":"The map option {x} is unknown. Allowed options: {\", \".join(allowed_key_map_options)}","messagePattern":"The map option (.+?) is unknown\\. Allowed options: (.+?)","errorType":"validation","errorClass":"KeyError","httpStatus":null,"severity":"error","filePath":"kitty/options/utils.py","lineNumber":1529,"sourceCode":"key_map_option_converters['allow_fallback'] = _convert_allow_fallback\n\n\ndef parse_options_for_map(val: str) -> tuple[KeyMapOptions, str]:\n    expecting_arg = ''\n    ans = KeyMapOptions()\n    s = Shlex(val)\n    while (tok := s.next_word())[0] > -1:\n        x = tok[1]\n        if expecting_arg:\n            object.__setattr__(ans, expecting_arg, key_map_option_converters[expecting_arg](x))\n            expecting_arg = ''\n        elif x.startswith('--'):\n            expecting_arg = x[2:]\n            k, sep, v = expecting_arg.partition('=')\n            k = k.replace('-', '_')\n            expecting_arg = k\n            if expecting_arg not in allowed_key_map_options:\n                raise KeyError(f'The map option {x} is unknown. Allowed options: {\", \".join(allowed_key_map_options)}')\n            if sep == '=':\n                object.__setattr__(ans, k, key_map_option_converters[k](v))\n                expecting_arg = ''\n        else:\n            return ans, val[tok[0] :]\n    return ans, ''\n\n\ndef parse_map(val: str) -> Iterable[KeyDefinition]:\n    parts = val.split(maxsplit=1)\n    options = default_key_map_options\n    if len(parts) == 2:\n        sc, action = parts\n        if sc.startswith('--'):\n            options, leftover = parse_options_for_map(val)\n            parts = leftover.split(maxsplit=1)\n            if len(parts) == 1:\n                sc, action = parts[0], ''","sourceCodeStart":1511,"sourceCodeEnd":1547,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/options/utils.py#L1511-L1547","documentation":"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.","triggerScenarios":"A map line like 'map --hidden f1 ...' where 'hidden' is not an allowed key map option; also '--some-opt=value' with a misspelled key.","commonSituations":"Typos in map options, using scrollbar/theme options that only apply elsewhere, or version drift where an option was renamed.","solutions":["Use only the allowed map options shown in the error message (e.g. mapped, launched, allow-fallback, etc.)","Fix typos; use dashes or underscores consistently (they are normalized)","Check kitty docs for key map options in your version"],"exampleFix":"# before\nmap --hide-from-cat f1 copy_to_clipboard\n# after\nmap --mapped f1 copy_to_clipboard","handlingStrategy":"type-guard","validationCode":"from kitty.options.utils import allowed_key_map_options\ndef valid_map_option(flag: str) -> bool:\n    return flag.lstrip('-').replace('-', '_') in allowed_key_map_options","typeGuard":"def is_valid_map_option(flag: str, allowed: set[str]) -> bool:\n    return flag.lstrip('-').replace('-', '_') in allowed","tryCatchPattern":null,"preventionTips":["Read the allowed list from the error message itself"],"tags":["kitty","config","keybindings","unknown-option"],"backgroundTag":"unknown-config-option","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}