kovidgoyal/kitty · warning

Mouse modes: {modes} not recognized, ignoring

Error message

Mouse modes: {modes} not recognized, ignoring

What it means

The modes field of a mouse_map line must be a comma-separated subset of {'grabbed','ungrabbed'}. Anything else causes the mapping to be ignored.

Source

Thrown at kitty/options/utils.py:1623

        if mods is None:
            return
    else:
        obutton = parts[0].lower()
        mods = 0
    try:
        b = mouse_button_map.get(obutton, obutton)[1:]
        button = getattr(defines, f'GLFW_MOUSE_BUTTON_{b}')
    except Exception:
        log_error(f'Mouse button: {xbutton} not recognized, ignoring')
        return
    try:
        count = mouse_trigger_count_map[event.lower()]
    except KeyError:
        log_error(f'Mouse event type: {event} not recognized, ignoring')
        return
    specified_modes = frozenset(modes.lower().split(','))
    if specified_modes - {'grabbed', 'ungrabbed'}:
        log_error(f'Mouse modes: {modes} not recognized, ignoring')
        return
    for mode in sorted(specified_modes):
        yield MouseMapping(button, mods, count, mode == 'grabbed', definition=action)


def parse_font_spec(spec: str) -> FontSpec:
    return FontSpec.from_setting(spec)


JumpTypes = Literal['start', 'end', 'none', 'both']


class EasingFunction(NamedTuple):
    type: Literal['steps', 'linear', 'cubic-bezier', ''] = ''

    num_steps: int = 0
    jump_type: JumpTypes = 'end'

View on GitHub (pinned to 6d5d0c4406)

Solutions

  1. Use only 'grabbed', 'ungrabbed', or 'grabbed,ungrabbed'.
  2. Remove trailing commas and stray spaces/tokens.
  3. Example: mouse_map left click grabbed,ungrabbed ...

Example fix

# before
mouse_map left click always paste

# after
mouse_map left click grabbed,ungrabbed paste
Defensive patterns

Strategy: validation

Validate before calling

def valid_mouse_modes(modes: str) -> bool:
    return set(modes.lower().split(',')) <= {'grabbed','ungrabbed'}

Type guard

def is_mode_list(modes: str) -> bool:
    toks = set(modes.lower().split(','))
    return toks and toks <= {'grabbed','ungrabbed'}

Prevention

When it happens

Trigger: 'mouse_map left click both ...' or modes containing 'grabbed, foo'.

Common situations: Expecting modes like 'always' or 'all'; trailing commas introducing empty tokens after splitting; typos like 'ungrabed'.

Related errors

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