kovidgoyal/kitty · error · ValueError

cursor_trail_start_threshold must have 1 or 2 values, got: {

Error message

cursor_trail_start_threshold must have 1 or 2 values, got: {x!r}

What it means

cursor_trail_start_threshold raises this when the option value does not have exactly 1 or 2 whitespace-separated positive integers. One value sets both x and y thresholds; two set them separately (default 2 2 in pixels).

Source

Thrown at kitty/options/utils.py:667

        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}')


def scrollback_lines(x: str) -> int:
    ans = int(x)
    if ans < 0:
        ans = 2**32 - 1
    return ans


def scrollback_pager_history_size(x: str) -> int:
    ans = int(max(0, float(x)) * 1024 * 1024)
    return min(ans, 4096 * 1024 * 1024 - 1)


# "single" for backwards compat
url_style_map = {'none': 0, 'single': 1, 'straight': 1, 'double': 2, 'curly': 3, 'dotted': 4, 'dashed': 5}

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Provide one or two space-separated positive integers
2. Restore default: cursor_trail_start_threshold 2 2

Example fix

# before
cursor_trail_start_threshold 2,2
# after
cursor_trail_start_threshold 2 2

def valid_threshold(x: str) -> bool:
    parts = x.split()
    return len(parts) in (1,2) and all(p.isdigit() and int(p) > 0 for p in parts)

When it happens

Trigger: cursor_trail_start_threshold 2,2 (commas), 0 -5 (non-positive fails positive_int), or three values.

Common situations: Using comma separators, zero/negative thresholds, or copy-paste errors from other pixel options.

Related errors

• This should be run as kitten broadcast
• No option named: {k}
• No custom kitten named {kitten} found
• Not a number: {x} with error: {e}
• Not a valid unit: {x}. Allowed units are: {default_unit}, {"

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