{"record":{"id":"840b95a12d39c7e3","repo":"kovidgoyal/kitty","slug":"the-cmd-to-run-must-be-specified-when-running-a-ba","errorCode":null,"errorMessage":"The cmd to run must be specified when running a background process","messagePattern":"The cmd to run must be specified when running a background process","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"kitty/launch.py","lineNumber":807,"sourceCode":"            final_cmd.append(x)\n        if rc_from_window is None and final_cmd:\n            exe = which(final_cmd[0])\n            if exe:\n                final_cmd[0] = exe\n        kw['cmd'] = final_cmd\n    if force_window_launch and opts.type not in non_window_launch_types:\n        opts.type = 'window'\n    if next_to and opts.type in non_window_launch_types:\n        next_to = None\n    base_for_overlay = next_to\n    if target_tab and (not base_for_overlay or base_for_overlay not in target_tab):\n        base_for_overlay = target_tab.active_window\n    if opts.type in ('overlay', 'overlay-main') and base_for_overlay:\n        kw['overlay_for'] = base_for_overlay.id\n    if opts.type == 'background':\n        cmd = kw['cmd']\n        if not cmd:\n            raise ValueError('The cmd to run must be specified when running a background process')\n        boss.run_background_process(\n            cmd,\n            cwd=kw['cwd'],\n            cwd_from=kw['cwd_from'],\n            env=env or None,\n            stdin=kw['stdin'],\n            allow_remote_control=kw['allow_remote_control'],\n            remote_control_passwords=kw['remote_control_passwords'],\n            notify_on_death=child_death_callback,\n        )\n    elif opts.type in ('clipboard', 'primary'):\n        stdin = kw.get('stdin')\n        if stdin is not None:\n            if opts.type == 'clipboard':\n                set_clipboard_string(stdin)\n                boss.handle_clipboard_loss('clipboard')\n            else:\n                set_primary_selection(stdin)","sourceCodeStart":789,"sourceCodeEnd":825,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/launch.py#L789-L825","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Append a concrete command: kitty @ launch --type=background -- some-cmd args.","Default to a no-op like 'true' or 'sleep infinity' if the command is genuinely optional in your tooling.","Validate non-empty cmd before issuing the launch in your scripts."],"exampleFix":"# before\nkitty @ launch --type=background\n# after\nkitty @ launch --type=background -- /usr/local/bin/sync-job","handlingStrategy":"validation","validationCode":"cmd = kw.get('cmd')\nassert cmd, 'background launch requires a command'","typeGuard":"def has_cmd(cmd) -> bool:\n    return bool(cmd and any(cmd))","tryCatchPattern":"try:\n    launch(...)\nexcept ValueError as e:\n    if 'background' in str(e): raise SystemExit(f'provide a command: {e}')\n    raise","preventionTips":["Always pass '-- <command>' after --type=background.","Default empty commands to a safe no-op in templated scripts."],"tags":["kitty","launch","background-process","missing-command"],"backgroundTag":"missing-required-argument","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}