kovidgoyal/kitty · warning

Shortcut: {sc} has unknown key, ignoring

Error message

Shortcut: {sc} has unknown key, ignoring

What it means

While parsing a multi-key shortcut sequence, one part parsed with key == 0 but had valid modifiers, meaning the key name itself was unrecognized. That shortcut definition is dropped.

Source

Thrown at kitty/options/utils.py:1567

                sc = parts[0]
                action = ' '.join(parts[1:])
    else:
        sc, action = val, ''
    sc, action = sc.strip().strip(sequence_sep), action.strip()
    if not sc:
        return
    is_sequence = sequence_sep in sc
    if is_sequence:
        trigger: SingleKey | None = None
        restl: list[SingleKey] = []
        for part in sc.split(sequence_sep):
            try:
                mods, is_native, key = parse_shortcut(part)
            except InvalidMods:
                return
            if key == 0:
                if mods is not None:
                    log_error(f'Shortcut: {sc} has unknown key, ignoring')
                return
            if trigger is None:
                trigger = SingleKey(mods, is_native, key)
            else:
                restl.append(SingleKey(mods, is_native, key))
        rest = tuple(restl)
    else:
        try:
            mods, is_native, key = parse_shortcut(sc)
        except InvalidMods:
            return
        if key == 0:
            if mods is not None:
                log_error(f'Shortcut: {sc} has unknown key, ignoring')
            return
    if is_sequence:
        if trigger is not None:
            yield KeyDefinition(True, trigger, rest, definition=action, options=options)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Correct the key name in the sequence segment to a kitty-recognized key (e.g. a, f1, space).
2. Simplify to test each segment as a single shortcut first.
3. Check kitty docs for key names.

Example fix

# before
map ctrl+a>ctrl+k close_window

# after
map ctrl+a>ctrl+w close_window

from kitty.key_encoding import parse_shortcut
def sequence_segments_ok(sc: str) -> bool:
    for part in sc.split('>'):
        try:
            mods, native, key = parse_shortcut(part)
            if key == 0:
                return False
        except Exception:
            return False
    return True

def is_valid_shortcut_sequence(sc: str) -> bool:
    return all(parse_ok(p) and key_nonzero(p) for p in sc.split('>'))

When it happens

Trigger: map ctrl+a>ctrl+k sequence where one segment has an invalid key, e.g. 'ctrl+a>ctrl+baad', or a key name kitty does not recognize in that position.

Common situations: Typos in key names; keys only available with specific keyboard layouts; mixing sequence separator '>' incorrectly.

Related errors

• Unknown action: {func}. Check if map action: {action} is val
• Unknown key action: {action}
• Failed to parse map = %#v with error: %w
• This should be run as kitten broadcast
• No option named: {k}

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