kovidgoyal/kitty · warning · ValueError

{second} is not a valid pointer shape name

Error message

{second} is not a valid pointer shape name

What it means

Raised by kitty's pointer_shape parser when the pointer shape specification contains a token that is not one of the recognized pointer shape names (e.g. arrow, beam, hand). The option expects 'default_shape' or a 'text_shape default_shape' pair; the second token defaults to the first but must itself be a valid shape name. It is thrown while parsing the pointer_shape setting in kitty.conf.

Source

Thrown at kitty/options/utils.py:1847

    'zoom-out',
    'alias',
    'copy',
    'not-allowed',
    'no-drop',
    'grab',
    'grabbing',
    # end pointer shape names
)


def pointer_shape_when_dragging(spec: str) -> tuple[str, str]:
    parts = spec.split(maxsplit=1)
    first = parts[0]
    if first not in pointer_shape_names:
        raise ValueError(f'{first} is not a valid pointer shape name')
    second = parts[1] if len(parts) > 1 else first
    if second not in pointer_shape_names:
        raise ValueError(f'{second} is not a valid pointer shape name')
    return first, second


def transparent_background_colors(spec: str) -> tuple[tuple[Color, float], ...]:
    if not spec:
        return ()
    ans: list[tuple[Color, float]] = []
    seen: dict[Color, int] = {}
    for part in spec.split():
        col, sep, alpha = part.partition('@')
        c = to_color(col)
        o = max(-1, min(float(alpha) if alpha else -1, 1))
        if (idx := seen.get(c)) is not None:
            ans[idx] = c, o
            continue
        seen[c] = len(ans)
        ans.append((c, o))
    return tuple(ans[:7])

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use a valid shape name: one of arrow, beam, hand (check pointer_shape_names in kitty/options/utils.py for the authoritative list)
2. If specifying two shapes ('text default'), verify both tokens individually
3. Remove the option to fall back to the default (arrow)

Example fix

# before
pointer_shape crosshair
pointer_shape text beam default

# after
pointer_shape hand
pointer_shape beam hand

from kitty.options.utils import pointer_shape_names  # or hardcode: {'arrow','beam','hand'}
valid = {'arrow', 'beam', 'hand'}
shapes = spec.split()
assert all(s in valid for s in shapes[:2]), f'invalid pointer shape in {spec!r}'

def is_pointer_shape_spec(spec: str) -> bool:
    names = {'arrow', 'beam', 'hand'}
    parts = spec.split()
    return 1 <= len(parts) <= 2 and all(p in names for p in parts)

When it happens

Trigger: Setting pointer_shape to a misspelled or unsupported name in kitty.conf, e.g. 'pointer_shape crosshair' or 'pointer_shape beam arrows' (misspelled plural). Any value not in the pointer_shape_names set on either position triggers it.

Common situations: Typos in kitty.conf after upgrading (supported shape names changed across versions), copy-pasting configs from other terminals that use different cursor names, or assuming X11 cursor names (like 'xterm') work here.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• The value {x} is not a known choice
• The value {val} is not a valid choice for progress_bar
• The value {val} is not a valid choice for scrollbar
• The value {val} is not a valid choice for strip_trailing_spa
• The value {val} is not a valid choice for tab_bar_align

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