kovidgoyal/kitty · error · ValueError

Unknown notify_on_cmd_finish action: {parts[2]}

Error message

Unknown notify_on_cmd_finish action: {parts[2]}

What it means

Raised by notify_on_cmd_finish when the third token (the action) is not one of notify, bell, notify-bell, command. The action selects how the finish is signaled.

Source

Thrown at kitty/options/utils.py:930

    action: str = 'notify'
    cmdline: tuple[str, ...] = ()
    clear_on: tuple[ClearOn, ...] = default_clear_on


def notify_on_cmd_finish(x: str) -> NotifyOnCmdFinish:
    parts = x.split(maxsplit=3)
    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:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use notify, bell, notify-bell, or command as the action
2. Omit the action to default to notify

Example fix

# before
notify_on_cmd_finish always 5.0 alart
# after
notify_on_cmd_finish always 5.0 notify

def is_notify_action(x: str) -> bool:
    return x in ('notify','bell','notify-bell','command')

When it happens

Trigger: notify_on_cmd_finish always 5.0 sound, or any misspelled action token when three or more tokens are present.

Common situations: Typos ('comand'), or expecting action names from other tools (e.g. 'alert').

Related errors

• Unknown notify_on_cmd_finish value: {parts[0]}
• notify_on_cmd_finish: notify clear_on value "{x}" is invalid
• 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/150f433d2744e4d2. Report an issue: GitHub.