kovidgoyal/kitty · error · ValueError

notify_on_cmd_finish `command` action needs a command line

Error message

notify_on_cmd_finish `command` action needs a command line

What it means

notify_on_cmd_finish with action 'command' requires a fourth token (the command line to run). If parts has no element after the action, this ValueError is raised.

Source

Thrown at kitty/options/utils.py:944

    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', ''):
        return ()
    from glob import glob

    x = resolve_abs_or_config_path(x, None)
    return tuple(x for x in sorted(glob(x)) if x.rpartition('.')[-1].lower() in ('jpeg', 'jpg', 'png', 'webp', 'tif', 'tiff', 'bmp', 'gif')) or (x,)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Append a shell command after the command action
2. Quote it if it contains spaces: notify_on_cmd_finish always 5.0 command notify-send done

Example fix

# before
notify_on_cmd_finish always 5.0 command
# after
notify_on_cmd_finish always 5.0 command notify-send 'kitty: command done'

def valid_notify_cmdline(x: str) -> bool:
    parts = x.split(maxsplit=3)
    return not (len(parts) > 2 and parts[2] == 'command' and len(parts) < 4)

When it happens

Trigger: notify_on_cmd_finish always 5.0 command — action given but no command string follows.

Common situations: Forgetting to append the command after 'command', or trailing whitespace-only command that gets split away.

Related errors

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