kovidgoyal/kitty · warning

Mouse button: {xbutton} not recognized, ignoring

Error message

Mouse button: {xbutton} not recognized, ignoring

What it means

The mouse button token could not be resolved to a GLFW_MOUSE_BUTTON_* constant (after applying mouse_button_map aliases and stripping 'b'). The mapping is ignored.

Source

Thrown at kitty/options/utils.py:1614

        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()]
    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)

View on GitHub (pinned to 6d5d0c4406)

Solutions

  1. Use standard names: left, right, middle, b1..b8, or wheel directions per docs.
  2. Fix typos like 'middle2'.
  3. Check mouse_button_map if you remapped aliases.

Example fix

# before
mouse_map middle2 click ungrabbed paste

# after
mouse_map middle click ungrabbed paste
Defensive patterns

Strategy: validation

Validate before calling

def valid_mouse_button(tok: str) -> bool:
    import re
    return bool(re.fullmatch(r'(ctrl\+|shift\+|alt\+|super\+)*(left|right|middle|b[1-8]|wheel_up|wheel_down)', tok, re.I))

Type guard

def is_known_mouse_button(tok: str) -> bool:
    base = tok.split('+')[-1].lower()
    return base in {'left','right','middle','b1','b2','b3','b4','b5','b6','b7','b8','wheel_up','wheel_down'}

Prevention

When it happens

Trigger: mouse_map middle2 click ... or 'mouse_map baux click ...' — unrecognized button names or malformed 'b<N>' forms cause the getattr to fail.

Common situations: Typos in button names; using wheel without proper event names; assuming arbitrary button numbers work without the b prefix.

Related errors

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