kovidgoyal/kitty · warning

clear_terminal needs two arguments, using defaults

Error message

clear_terminal needs two arguments, using defaults

What it means

The clear_terminal action in a map definition needs two arguments (an action and 'active'/'inactive') but fewer were provided. kitty substitutes defaults ['reset', True] so the mapping still triggers a reset.

Source

Thrown at kitty/options/utils.py:253

def parse_change_font_size(func: str, rest: str) -> tuple[str, tuple[bool, str | None, float]]:
    vals = rest.strip().split(maxsplit=1)
    if len(vals) != 2:
        log_error(f'Invalid change_font_size specification: {rest}, treating it as default')
        return func, (True, None, 0)
    c_all = vals[0].lower() == 'all'
    sign: str | None = None
    amt = vals[1]
    if amt[0] in '+-*/':
        sign = amt[0]
        amt = amt[1:]
    return func, (c_all, sign, float(amt.strip()))


@func_with_args('clear_terminal')
def clear_terminal(func: str, rest: str) -> FuncArgsType:
    vals = rest.strip().split(maxsplit=1)
    if len(vals) != 2:
        log_error('clear_terminal needs two arguments, using defaults')
        args = ['reset', True]
    else:
        action = vals[0].lower()
        if action not in ('reset', 'scroll', 'scrollback', 'clear', 'to_cursor', 'to_cursor_scroll', 'last_command'):
            log_error(f'{action} is unknown for clear_terminal, using reset')
            action = 'reset'
        args = [action, vals[1].lower() == 'active']
    return func, args


@func_with_args('copy_to_buffer')
def copy_to_buffer(func: str, rest: str) -> FuncArgsType:
    return func, [rest]


@func_with_args('paste_from_buffer')
def paste_from_buffer(func: str, rest: str) -> FuncArgsType:
    return func, [rest]

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Provide both arguments, e.g. `map f1 clear_terminal reset active`
2. Use one of the valid actions: reset, scroll, scrollback, clear, to_cursor, to_cursor_scroll, last_command

Example fix

# before
map f1 clear_terminal reset
# after
map f1 clear_terminal reset active

rest = 'reset active'
vals = rest.strip().split(maxsplit=1)
ok = len(vals) == 2 and vals[0].lower() in ('reset','scroll','scrollback','clear','to_cursor','to_cursor_scroll','last_command')

When it happens

Trigger: `map f1 clear_terminal reset` (single token) or an empty argument string — rest.strip().split(maxsplit=1) yields fewer than 2 parts.

Common situations: Writing clear_terminal with only the action and forgetting the second boolean-ish argument in kitty.conf.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• {action} is unknown for clear_terminal, using reset
• Unknown marker type: {ftype}
• {rest} is not a valid marker specification
• {rest} is not a valid scroll_to_mark destination
• Unknown signal: {rest} ignoring

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