kovidgoyal/kitty · warning

Invalid mouse_hide_wait: {x}, ignoring

Error message

Invalid mouse_hide_wait: {x}, ignoring

What it means

mouse_hide_wait must be either a single number or exactly four tokens (base multiplier interval-to-repeat enable-flag). Any other token count logs this warning and falls back to defaults (3.0 0.0 40 True).

Source

Thrown at kitty/options/utils.py:1790

            raise KeyError(f'{func_name} is not a valid easing function')
    return interval, m[0], m[1]


def cursor_blink_interval(spec: str) -> tuple[float, EasingFunction, EasingFunction]:
    return parse_animation(spec)


class MouseHideWait(NamedTuple):
    hide_wait: float
    show_wait: float
    show_threshold: int
    scroll_show: bool


def mouse_hide_wait(x: str) -> MouseHideWait:
    parts = x.split(maxsplit=3)
    if len(parts) != 1 and len(parts) != 4:
        log_error(f'Invalid mouse_hide_wait: {x}, ignoring')
        return MouseHideWait(3.0, 0.0, 40, True)
    if len(parts) == 1:
        return MouseHideWait(float(parts[0]), 0.0, 40, True)
    else:
        return MouseHideWait(float(parts[0]), float(parts[1]), int(parts[2]), to_bool(parts[3]))


def visual_bell_duration(spec: str) -> tuple[float, EasingFunction, EasingFunction]:
    return parse_animation(spec, interval=0.0)


pointer_shape_names = (
    # start pointer shape names (auto generated by gen-key-constants.py do not edit)
    'arrow',
    'beam',
    'text',
    'pointer',
    'hand',

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use a single number: mouse_hide_wait 3.0
2. Or the full 4-token form: mouse_hide_wait <base> <multiplier> <repeat-interval> <bool>, e.g. mouse_hide_wait 3.0 0.0 40 true
3. Do not use 2 or 3 tokens.

Example fix

# before
mouse_hide_wait 3 0

# after
mouse_hide_wait 3.0 0.0 40 true

def valid_mouse_hide_wait(x: str) -> bool:
    n = len(x.split())
    return n == 1 or n == 4

def is_mhw_arity(x: str) -> bool:
    n = len(x.split())
    return n in (1, 4)

When it happens

Trigger: 'mouse_hide_wait 3 0' (2 tokens) or 'mouse_hide_wait 3 0 40' (3 tokens) instead of 1 or 4 tokens.

Common situations: Partially filling the extended form; older configs migrating to the 4-value syntax; forgetting the boolean tail token.

Related errors

• Ignoring invalid mouse action: {val}
• Mouse button: {xbutton} not recognized, ignoring
• Mouse event type: {event} not recognized, ignoring
• Mouse modes: {modes} not recognized, ignoring
• This should be run as kitten broadcast

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