kovidgoyal/kitty · error · ValueError

{rest} is not a valid marker specification

Error message

{rest} is not a valid marker specification

What it means

toggle_marker in kitty/options/utils.py raises this when the argument string to toggle_marker cannot be split into exactly two whitespace-separated parts (marker type and spec). It means the action was given fewer or more than the required two components.

Source

Thrown at kitty/options/utils.py:454

                raise ValueError(f'Mark group in marker specification is not an integer: {parts[i]}')
            sspec = parts[i + 1]
            if 'regex' not in ftype:
                sspec = re.escape(sspec)
            ans.append((color, sspec))
        ftype = 'regex'
        spec: str | tuple[tuple[int, str], ...] = tuple(ans)
    elif ftype == 'function':
        spec = ' '.join(parts)
    else:
        raise ValueError(f'Unknown marker type: {ftype}')
    return ftype, spec, flags


@func_with_args('toggle_marker')
def toggle_marker(func: str, rest: str) -> FuncArgsType:
    parts = rest.split(maxsplit=1)
    if len(parts) != 2:
        raise ValueError(f'{rest} is not a valid marker specification')
    ftype, spec = parts
    parts = list(shlex_split(spec))
    return func, list(parse_marker_spec(ftype, parts))


@func_with_args('scroll_to_mark')
def scroll_to_mark(func: str, rest: str) -> FuncArgsType:
    parts = rest.split()
    if not parts or not rest:
        return func, [True, 0]
    if len(parts) == 1:
        q = parts[0].lower()
        if q in ('prev', 'previous', 'next'):
            return func, [q != 'next', 0]
        try:
            return func, [True, max(0, min(int(q), 3))]
        except Exception:
            raise ValueError(f'{rest} is not a valid scroll_to_mark destination')

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Provide both the marker type and the spec: toggle_marker <ftype> <spec>
2. Verify the map line in kitty.conf has the full two-part argument

Example fix

# before
map f1 toggle_marker regex
# after
map f1 toggle_marker regex ERROR.*

def valid_toggle_marker_arg(rest: str) -> bool:
    return len(rest.split(maxsplit=1)) == 2

When it happens

Trigger: Mapping or remote-calling toggle_marker with a single word (map f1 toggle_marker regex) or with leading/trailing structure that yields != 2 parts after rest.split(maxsplit=1).

Common situations: Copy-paste of set_marker syntax into toggle_marker, forgetting the spec portion, or trailing whitespace collapse issues in kitty.conf.

Related errors

• Unknown marker type: {ftype}
• {rest} is not a valid scroll_to_mark destination
• clear_terminal needs two arguments, using defaults
• {action} is unknown for clear_terminal, using reset
• This should be run as kitten broadcast

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