kovidgoyal/kitty · error · ValueError

The cmd to run must be specified when running a background p

Error message

The cmd to run must be specified when running a background process

What it means

For --type=background launches, kitty does not create a window, so there is nothing to run except the supplied command; an empty cmd triggers ValueError('The cmd to run must be specified when running a background process').

Source

Thrown at kitty/launch.py:807

            final_cmd.append(x)
        if rc_from_window is None and final_cmd:
            exe = which(final_cmd[0])
            if exe:
                final_cmd[0] = exe
        kw['cmd'] = final_cmd
    if force_window_launch and opts.type not in non_window_launch_types:
        opts.type = 'window'
    if next_to and opts.type in non_window_launch_types:
        next_to = None
    base_for_overlay = next_to
    if target_tab and (not base_for_overlay or base_for_overlay not in target_tab):
        base_for_overlay = target_tab.active_window
    if opts.type in ('overlay', 'overlay-main') and base_for_overlay:
        kw['overlay_for'] = base_for_overlay.id
    if opts.type == 'background':
        cmd = kw['cmd']
        if not cmd:
            raise ValueError('The cmd to run must be specified when running a background process')
        boss.run_background_process(
            cmd,
            cwd=kw['cwd'],
            cwd_from=kw['cwd_from'],
            env=env or None,
            stdin=kw['stdin'],
            allow_remote_control=kw['allow_remote_control'],
            remote_control_passwords=kw['remote_control_passwords'],
            notify_on_death=child_death_callback,
        )
    elif opts.type in ('clipboard', 'primary'):
        stdin = kw.get('stdin')
        if stdin is not None:
            if opts.type == 'clipboard':
                set_clipboard_string(stdin)
                boss.handle_clipboard_loss('clipboard')
            else:
                set_primary_selection(stdin)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Append a concrete command: kitty @ launch --type=background -- some-cmd args.
2. Default to a no-op like 'true' or 'sleep infinity' if the command is genuinely optional in your tooling.
3. Validate non-empty cmd before issuing the launch in your scripts.

Example fix

# before
kitty @ launch --type=background
# after
kitty @ launch --type=background -- /usr/local/bin/sync-job

cmd = kw.get('cmd')
assert cmd, 'background launch requires a command'

def has_cmd(cmd) -> bool:
    return bool(cmd and any(cmd))

try:
    launch(...)
except ValueError as e:
    if 'background' in str(e): raise SystemExit(f'provide a command: {e}')
    raise

When it happens

Trigger: Calling launch with type='background' and no command line in kw['cmd'] — e.g. kitty @ launch --type=background with no trailing command, or a launch config whose cmdline evaluated empty.

Common situations: Scripts templating launch commands where the command variable is empty; configs relying on shell-expansion that yields nothing; users assuming background spawns a default shell.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Unknown type_of_input: {type_of_input}
• usage: kitty +launch script.py [arguments to be passed to sc
• {argparse error from SystemExit}
• --hold-after-ssh can only be supplied if --cwd=current or si
• This must be run as kitten ask

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