kovidgoyal/kitty · warning

Shortcut: {sc} has unknown modifier, ignoring

Error message

Shortcut: {sc} has unknown modifier, ignoring

What it means

While parsing a shortcut/mouse-map modifier list, a token did not map to any GLFW_MOD_* constant, so kitty discards the whole shortcut (parse_mods returns None). Unlike most kitty fallbacks, this one removes the mapping entirely.

Source

Thrown at kitty/options/utils.py:517

def load_config_file(func: str, rest: str) -> FuncArgsType:
    return func, list(shlex_split(rest))


# }}}


def parse_mods(parts: Iterable[str], sc: str) -> int | None:

    def map_mod(m: str) -> str:
        return mod_map.get(m, m)

    mods = 0
    for m in parts:
        try:
            mods |= getattr(defines, f'GLFW_MOD_{map_mod(m.upper())}')
        except AttributeError:
            if m.upper() != 'NONE':
                log_error(f'Shortcut: {sc} has unknown modifier, ignoring')
            return None

    return mods


def to_modifiers(val: str) -> int:
    return parse_mods(val.split('+'), val) or 0


def remap_modifiers(val: str) -> dict[int, int]:
    # Only the real modifiers may be remapped. parse_mods() also accepts
    # kitty_mod (a parse-time placeholder resolved out of keymaps before any key
    # event exists) and the lock modifiers, neither of which can be meaningfully
    # carried on an event, so they are rejected here rather than silently
    # mangling events later.
    ans = {}
    if not val:
        return ans

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use kitty's modifier names: ctrl, shift, alt, super, hyper, meta (plus platform mapping via map_mod e.g. cmd/apple on macOS)
2. Fix typos in the modifier portion of the map/mouse_map line

Example fix

# before
map ctrl+meat+t new_tab
# after
map ctrl+meta+t new_tab

mods = 'ctrl+meta'.split('+')
from kitty import defines
ok = all(hasattr(defines, f'GLFW_MOD_{m.upper()}') for m in mods)

When it happens

Trigger: `map ctrl+alt+x ...` is fine, but `map ctrl+win+hyper+meat+x ...` fails because 'meat' has no defines.GLFW_MOD_MEAT; also 'NONE' mixed with other mods is silently ignored without logging.

Common situations: Typos in modifier names (ctrl, shift, alt, super/cmd, hyper, meta), platform-specific names like 'option' or 'command' instead of kitty's 'alt'/'super'.

Related errors

• Ignoring invalid remap_modifiers "{val}": {msg}
• Invalid shortcut
• Unknown signal: {rest} ignoring
• Invalid change_font_size specification: {rest}, treating it
• clear_terminal needs two arguments, using defaults

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