kovidgoyal/kitty · error · KeyError

Unknown action: {func}

Error message

Unknown action: {func}

What it means

When a key action in a map line has arguments (a second token), kitty looks up a parser for the action name in func_with_args. An unregistered name raises KeyError with this message.

Source

Thrown at kitty/options/utils.py:1254

def symbol_map(val: str) -> Iterable[tuple[tuple[int, int], str]]:
    yield from symbol_map_parser(val)


def narrow_symbols(val: str) -> Iterable[tuple[tuple[int, int], int]]:
    for x, y in symbol_map_parser(val, min_size=1):
        yield x, int(y or 1)


def parse_key_action(action: str, action_type: MapType = MapType.MAP) -> KeyAction:
    parts = action.strip().split(maxsplit=1)
    func = parts[0]
    if len(parts) == 1:
        return KeyAction(func, ())
    rest = parts[1]
    parser = func_with_args.get(func)
    if parser is None:
        raise KeyError(f'Unknown action: {func}')
    func, args = parser(func, rest)
    return KeyAction(func, tuple(args))


class ActionAlias(NamedTuple):
    name: str
    value: str
    replace_second_arg: bool = False


class AliasMap:
    def __init__(self) -> None:
        self.aliases: dict[str, list[ActionAlias]] = {}

    def append(self, name: str, aa: ActionAlias) -> None:
        self.aliases.setdefault(name, []).append(aa)

    def update(self, aa: 'AliasMap') -> None:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Correct the action name via 'kitty --debug-keyboard' or docs listing
2. If the action takes no arguments, remove the extra argument so it isn't parsed via func_with_args
3. Check action availability in your kitty version (run kitty +list-actions)

Example fix

# before
map f1 new_window_with_profile default
# after
map f1 launch --type=window

from kittens.tui.loop import func_with_args  # or kitty's action registry
def action_exists(name: str) -> bool:
    return name in func_with_args or name in known_no_arg_actions

def is_known_action(name: str, registry: dict) -> bool:
    return name in registry

try:
    ka = parse_key_action(val)
except KeyError as e:
    if 'Unknown action' in str(e):
        log.warning(f'skipping unknown action: {e}')
    raise

When it happens

Trigger: map lines like 'map f1 someunknownaction arg' where someunknownaction is not a known kitty action; misspelled action names (e.g. 'send_text2', 'launchh') or actions from a newer/older kitty version.

Common situations: Typos in action names, using actions removed in upgrades, or passing args to an action that takes none so it isn't in the parser table.

Related errors

• allow_fallback values must be a subset of shifted, ascii, go
• The map option {x} is unknown. Allowed options: {", ".join(a
• This should be run as kitten broadcast
• No option named: {k}
• No custom kitten named {kitten} found

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