kovidgoyal/kitty · error · KeyError

Unknown action: {func}. Check if map action: {action} is val

Error message

Unknown action: {func}. Check if map action: {action} is valid

What it means

parse_kittens_func_args looks up the map action's function name in the args_funcs registry; an unknown name raises KeyError with a hint to check whether the map action is valid. This is for kitten map actions inside kitten config files.

Source

Thrown at kitty/conf/utils.py:530

    def pretty(self) -> str:
        ans = self.func
        for x in self.args:
            ans += f' {x}'
        return ans


def parse_kittens_func_args(action: str, args_funcs: dict[str, KeyFunc[tuple[str, Any]]]) -> KeyAction:
    parts = action.strip().split(' ', 1)
    func = parts[0]
    if len(parts) == 1:
        return KeyAction(func, ())
    rest = parts[1]

    try:
        parser = args_funcs[func]
    except KeyError as e:
        raise KeyError(f'Unknown action: {func}. Check if map action: {action} is valid') from e

    try:
        func, args = parser(func, rest)
    except Exception:
        raise ValueError(f'Unknown key action: {action}')

    if not isinstance(args, (list, tuple)):
        args = (args,)

    return KeyAction(func, tuple(args))


KittensKeyDefinition = tuple[ParsedShortcut, KeyAction]
KittensKeyMap = dict[ParsedShortcut, KeyAction]


def parse_kittens_key(val: str, funcs_with_args: dict[str, KeyFunc[tuple[str, Any]]]) -> KittensKeyDefinition | None:
    from ..key_encoding import parse_shortcut

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the kitten's documented actions and fix the name
2. Update kitty/kitten to a version providing that action
3. Use launch/--type=kitten syntax for actions not natively supported

Example fix

# before
map ctrl+e send_text all not_a_real_action
# after
map ctrl+e close_window

known_actions = set(args_funcs)  # from the kitten's option parser
if action_name not in known_actions:
    raise ValueError(f'unknown kitten action {action_name}; known: {sorted(known_actions)}')

def is_known_kitten_action(args_funcs: dict, name: str) -> bool:
    return name in args_funcs

try:
    parse_kittens_func_args(action)
except KeyError as e:
    if 'Unknown action' in str(e):
        drop_or_rename_map_line(action)
    else:
        raise

When it happens

Trigger: A map line in a kitten's config using an action name that the kitten's option parser does not register, e.g. `map ctrl+x does_not_exist` inside a custom kitten conf.

Common situations: Typos in action names, actions only available in newer kitten versions, or using global kitty actions in a kitten context.

Related errors

• Unknown key action: {action}
• No option named: {k}
• Failed to parse map = %#v with error: %w
• Shortcut: {sc} has unknown key, ignoring
• This should be run as kitten broadcast

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