kovidgoyal/kitty · warning

Ignoring invalid mouse action: {val}

Error message

Ignoring invalid mouse action: {val}

What it means

A mouse_map line must split into at least 3 parts (button event [modes [action]]). With fewer than 3 tokens kitty logs this and ignores the mapping.

Source

Thrown at kitty/options/utils.py:1599

                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)
    else:
        assert key is not None
        yield KeyDefinition(False, SingleKey(mods, is_native, key), definition=action, options=options)


def parse_mouse_map(val: str) -> Iterable[MouseMapping]:
    parts = val.split(maxsplit=3)
    if len(parts) == 4:
        xbutton, event, modes, action = parts
    elif len(parts) > 2:
        xbutton, event, modes = parts
        action = ''
    else:
        log_error(f'Ignoring invalid mouse action: {val}')
        return
    kparts = xbutton.split('+')
    if len(kparts) > 1:
        mparts, obutton = kparts[:-1], kparts[-1].lower()
        mods = parse_mods(mparts, obutton)
        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()]

View on GitHub (pinned to 6d5d0c4406)

Solutions

  1. Use the full form: mouse_map <button(+mods)> <event> <modes> [action].
  2. Example: mouse_map left click ungrabbed mouse_handle_click selection link prompt
  3. Ensure at least 3 whitespace-separated fields.

Example fix

# before
mouse_map right click

# after
mouse_map right click ungrabbed paste
Defensive patterns

Strategy: validation

Validate before calling

def valid_mouse_map_line(val: str) -> bool:
    return len(val.split()) >= 3

Type guard

def is_mouse_map_armed(val: str) -> bool:
    return len(val.split()) >= 3

Prevention

When it happens

Trigger: mouse_map with only 1-2 tokens, e.g. 'mouse_map left click' missing modes, or 'mouse_map right press grabbed' where modes is present but action missing is still 3 tokens (valid); under 3 tokens fails.

Common situations: Omitting the modes ('grabbed'/'ungrabbed') argument; writing action-only lines; broken multi-line paste.

Related errors

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