kovidgoyal/kitty · error · ValueError

notify_on_cmd_finish: notify clear_on value "{x}" is invalid

Error message

notify_on_cmd_finish: notify clear_on value "{x}" is invalid. Valid values are: {", ".join(all_clear_on)}

What it means

When the notify_on_cmd_finish action starts with 'notify', an optional fourth token lists clear_on conditions, each of which must be in all_clear_on. Any invalid word raises this error listing valid values (e.g. visible, focused, unfocused — depending on kitty version).

Source

Thrown at kitty/options/utils.py:937

    if parts[0] not in ('never', 'unfocused', 'invisible', 'always'):
        raise ValueError(f'Unknown notify_on_cmd_finish value: {parts[0]}')
    when = parts[0]
    duration = 5.0
    if len(parts) > 1:
        duration = float(parts[1])
    action = 'notify'
    cmdline: tuple[str, ...] = ()
    clear_on = default_clear_on
    if len(parts) > 2:
        if parts[2] not in ('notify', 'bell', 'notify-bell', 'command'):
            raise ValueError(f'Unknown notify_on_cmd_finish action: {parts[2]}')
        action = parts[2]
        if action.startswith('notify'):
            if len(parts) > 3:
                con: list[ClearOn] = []
                for x in parts[3].split():
                    if x not in all_clear_on:
                        raise ValueError(f'notify_on_cmd_finish: notify clear_on value "{x}" is invalid. Valid values are: {", ".join(all_clear_on)}')
                    con.append(cast(ClearOn, x))
                clear_on = tuple(con)
        elif action == 'command':
            if len(parts) > 3:
                cmdline = tuple(to_cmdline(parts[3]))
            else:
                raise ValueError('notify_on_cmd_finish `command` action needs a command line')
    return NotifyOnCmdFinish(when, duration, action, cmdline, clear_on)


def config_or_absolute_path(x: str, env: dict[str, str] | None = None) -> str | None:
    if not x or x.lower() == 'none':
        return None
    return resolve_abs_or_config_path(x, env)


def background_images(x: str) -> tuple[str, ...]:
    if x.lower() in ('none', ''):

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use only the clear_on values shown in the error message
2. Drop the fourth token to accept defaults

Example fix

# before
notify_on_cmd_finish always 5 notify seen
# after
notify_on_cmd_finish always 5 notify visible

def valid_clear_on(tok: str, all_clear_on: set[str]) -> bool:
    return all(w in all_clear_on for w in tok.split())

When it happens

Trigger: notify_on_cmd_finish always 5 notify seen or any clear_on word not in the allowed set.

Common situations: Guessing clear-condition names, version differences in the allowed clear_on values.

Related errors

• Unknown notify_on_cmd_finish value: {parts[0]}
• Unknown notify_on_cmd_finish action: {parts[2]}
• notify_on_cmd_finish `command` action needs a command line
• This should be run as kitten broadcast
• This must be run as kitten desktop-ui

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