kovidgoyal/kitty · error · ValueError

{first} is not a valid pointer shape name

Error message

{first} is not a valid pointer shape name

What it means

pointer_shape_when_dragging takes one or two pointer shape names from pointer_shape_names (e.g. default, text, pointer, grab...). The first token is validated here and rejected if unknown.

Source

Thrown at kitty/options/utils.py:1844

    'nesw-resize',
    'nwse-resize',
    'zoom-in',
    '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

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use a valid pointer shape name (see kitty docs: default, text, pointer, grab, grabbing, crosshair, etc.)
2. If passing two shapes, validate both tokens

Example fix

# before
pointer_shape_when_dragging arrowhead
# after
pointer_shape_when_dragging grab

from kitty.options.utils import pointer_shape_names
def valid_pointer_shape(spec: str) -> bool:
    parts = spec.split()
    return bool(parts) and all(p in pointer_shape_names for p in parts[:2])

def is_pointer_shape(name: str, allowed: frozenset[str]) -> bool:
    return name in allowed

When it happens

Trigger: Setting 'pointer_shape_when_dragging arrow2' or any name not in kitty's pointer shape list; also invalid second token (same message, raised a few lines below).

Common situations: Guessing CSS cursor names kitty doesn't implement, typos, or using shapes added in newer kitty versions on an older build.

Related errors

• The value {x} is not a known choice
• Invalid value for {self._name}: {value!r}
• {jt} is not a valid jump type for a linear easing function
• {second} is not a valid pointer shape name
• This should be run as kitten broadcast

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