kovidgoyal/kitty · error · ValueError

Invalid cursor shape: {} allowed values are {}

Error message

Invalid cursor shape: {} allowed values are {}

What it means

to_cursor_shape raises this when the cursor_shape option value is not in the cshapes mapping: block, beam, underline (and newer variants like hollow_block in recent kitty versions). It formats the bad value with the list of allowed shapes.

Source

Thrown at kitty/options/utils.py:644

        return None
    return to_color(x)


cshapes = {'block': CURSOR_BLOCK, 'beam': CURSOR_BEAM, 'underline': CURSOR_UNDERLINE}
cshapes_unfocused = {
    'block': CURSOR_BLOCK,
    'beam': CURSOR_BEAM,
    'underline': CURSOR_UNDERLINE,
    'hollow': CURSOR_HOLLOW,
    'unchanged': NO_CURSOR_SHAPE,
}


def to_cursor_shape(x: str) -> int:
    try:
        return cshapes[x.lower()]
    except KeyError:
        raise ValueError('Invalid cursor shape: {} allowed values are {}'.format(x, ', '.join(cshapes)))


def to_cursor_unfocused_shape(x: str) -> int:
    try:
        return cshapes_unfocused[x.lower()]
    except KeyError:
        raise ValueError('Invalid unfocused cursor shape: {} allowed values are {}'.format(x, ', '.join(cshapes_unfocused)))


def cursor_trail_decay(x: str) -> tuple[float, float]:
    fast, slow = map(positive_float, x.split())
    slow = max(slow, fast)
    return fast, slow


def cursor_trail_start_threshold(x: str) -> tuple[int, int]:
    parts = x.split()
    if len(parts) == 1:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use block, beam, or underline
2. For unfocused cursor use cursor_shape_unfocused with the same values

Example fix

# before
cursor_shape i-beam
# after
cursor_shape beam

def is_cursor_shape(x: str) -> bool:
    return x.lower() in {'block','beam','underline'}

When it happens

Trigger: cursor_shape vertical, cursor_shape ibeam, or any typo in kitty.conf / remote-control set-option calls.

Common situations: Using terminology from other terminals (i-beam, vertical bar) instead of kitty's 'beam'; version differences in allowed shapes.

Related errors

• Invalid unfocused cursor shape: {} allowed values are {}
• {second} is not a valid pointer shape name
• This should be run as kitten broadcast
• No option named: {k}
• No custom kitten named {kitten} found

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