kovidgoyal/kitty · warning

{action} is unknown for clear_terminal, using reset

Error message

{action} is unknown for clear_terminal, using reset

What it means

The first argument to clear_terminal is not one of the recognized action names, so kitty resets it to 'reset'. The mapping still fires but performs a full terminal reset instead of the intended action.

Source

Thrown at kitty/options/utils.py:258

    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]


@func_with_args('paste')
def paste_parse(func: str, rest: str) -> FuncArgsType:
    text = ''

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Correct the action name to one of: reset, scroll, scrollback, clear, to_cursor, to_cursor_scroll, last_command
2. Reload config (ctrl+shift+f5 or restart) after fixing to confirm the message disappears

Example fix

# before
map f1 clear_terminal wipe active
# after
map f1 clear_terminal scrollback active

action = 'scrollback'
ok = action in ('reset','scroll','scrollback','clear','to_cursor','to_cursor_scroll','last_command')

When it happens

Trigger: `map f1 clear_terminal wipe active` — 'wipe' is not in ('reset','scroll','scrollback','clear','to_cursor','to_cursor_scroll','last_command').

Common situations: Typos in the action name, or assuming a clear action from another terminal emulator exists in kitty.

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

• clear_terminal needs two arguments, using defaults
• 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/07589261e898d7c5. Report an issue: GitHub.