kovidgoyal/kitty · error · ValueError

Invalid unfocused cursor shape: {} allowed values are {}

Error message

Invalid unfocused cursor shape: {} allowed values are {}

What it means

Same as cursor_shape but for cursor_shape_unfocused (to_cursor_unfocused_shape). Raised when the value is not in cshapes_unfocused, which may additionally include 'hollow' variants depending on kitty version.

Source

Thrown at kitty/options/utils.py:651

    '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:
        val = positive_int(parts[0])
        return val, val
    if len(parts) == 2:
        return positive_int(parts[0]), positive_int(parts[1])
    raise ValueError(f'cursor_trail_start_threshold must have 1 or 2 values, got: {x!r}')

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use an allowed value from the error message list (e.g. block, beam, underline, hollow_block)
2. Upgrade kitty if you need a newer shape name

Example fix

# before
cursor_shape_unfocused hollow-blok
# after
cursor_shape_unfocused hollow_block

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

When it happens

Trigger: cursor_shape_unfocused <typo> in kitty.conf, e.g. cursor_shape_unfocused hollow-blok.

Common situations: Typos, or expecting a shape that only exists in newer/older kitty versions.

Related errors

• Invalid 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/392a7ef0d18ca976. Report an issue: GitHub.