kovidgoyal/kitty · error · ValueError

Unknown key action: {action}

Error message

Unknown key action: {action}

What it means

The companion error to 54: when the action name resolves but its argument parser throws (bad or malformed arguments for the action), parse_kittens_func_args re-raises ValueError('Unknown key action: {action}') covering the whole map line.

Source

Thrown at kitty/conf/utils.py:535

        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

    sc, action = val.partition(' ')[::2]
    if not sc or not action:
        return None
    ans = parse_kittens_func_args(action, funcs_with_args)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the action's expected arguments in docs and fix them
2. Quote/escape arguments containing spaces
3. Match the action syntax to your kitty version

Example fix

# before
map ctrl+x send_text
# after
map ctrl+x send_text all hello

# validate against the action's expected argument shape before parsing
parts = action.split(' ', 1)
assert len(parts) == 2, 'action needs arguments'

try:
    parse_kittens_func_args(action)
except ValueError as e:
    if 'Unknown key action' in str(e):
        log_config_error(action)
    else:
        raise

When it happens

Trigger: A recognized kitten map action whose argument string fails parsing, e.g. wrong argument count or invalid argument format.

Common situations: Argument syntax changes across kitty versions; copy-pasted map lines from other kittens with different action signatures.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Unknown action: {func}. Check if map action: {action} is val
• Not a number: {x} with error: {e}
• Not a valid unit: {x}. Allowed units are: {default_unit}, {"
• Invalid number with unit: {x}
• Failed to parse map = %#v with error: %w

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