What causes "Unknown notify_on_cmd_finish value: {parts[0]}" in kovidgoyal/kitty?

Use never, unfocused, invisible, or always as the first word

kovidgoyal/kitty · error · ValueError

Unknown notify_on_cmd_finish value: {parts[0]}

Error message

Unknown notify_on_cmd_finish value: {parts[0]}

What it means

notify_on_cmd_finish raises this when the first token is not one of never, unfocused, invisible, always. This token controls when a command-finish notification fires.

Source

Thrown at kitty/options/utils.py:920


ClearOn = Literal['next', 'focus']
default_clear_on: tuple[ClearOn, ...] = 'focus', 'next'
all_clear_on = get_args(ClearOn)


class NotifyOnCmdFinish(NamedTuple):
    when: str = 'never'
    duration: float = 5.0
    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))

View on GitHub (pinned to 6d5d0c4406)

Solutions

Use never, unfocused, invisible, or always as the first word
Restore default: notify_on_cmd_finish never

Example fix

# before
notify_on_cmd_finish off
# after
notify_on_cmd_finish unfocused

Defensive patterns

Strategy: type-guard

Type guard

def is_notify_when(x: str) -> bool:
    return x in ('never','unfocused','invisible','always')

Prevention

First token must be one of the four documented values

When it happens

Trigger: notify_on_cmd_finish off, notify_on_cmd_finish focus in kitty.conf; also when the value line is empty of a valid first word.

Common situations: Using terminology from shell integrations or other terminals ('on', 'disable'), typos like 'allways'.

Related errors

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