kovidgoyal/kitty · info · SystemExit

This should be run as kitten clipboard

Error message

This should be run as kitten clipboard

What it means

kitty's VT parser encountered an escape sequence it does not implement and reports it via _report_unknown_escape_code (kitty/vt-parser.c). By default it goes to the error log; with a dump callback (remote control / debug kitten) it is forwarded to Python instead. Only the first 64 bytes of the sequence are shown, with a category name (CSI/DCS/OSC/etc.).

Source

Thrown at kittens/clipboard/main.py:95

    # Copy an image and some text to the clipboard:
    kitten clipboard picture.jpg text.txt

    # Copy text from STDIN and an image to the clipboard:
    echo hello | kitten clipboard picture.png /dev/stdin

    # Copy any raster image available on the clipboard to a PNG file:
    kitten clipboard -g picture.png

    # Copy an image to a file and text to STDOUT:
    kitten clipboard -g picture.png /dev/stdout

    # List the formats available on the system clipboard
    kitten clipboard -g -m . /dev/stdout
"""

usage = '[files to copy to/from]'
if __name__ == '__main__':
    raise SystemExit('This should be run as kitten clipboard')
elif __name__ == '__doc__':
    from kitty.simple_cli_definitions import CompletionSpec

    cd = sys.cli_docs  # type: ignore
    cd['usage'] = usage
    cd['options'] = OPTIONS
    cd['help_text'] = help_text
    cd['short_desc'] = 'Copy/paste with the system clipboard, even over SSH'
    cd['args_completion'] = CompletionSpec.from_string('type:file mime:* group:Files')

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Identify the emitting program by running apps one at a time or using kitty's debug input (ctrl+shift+f7 / kitten show-key).
2. Update kitty - newer versions implement more escape codes (shell integration, etc.).
3. Report the unimplemented sequence to kitty's GitHub if it's a standardized one.
4. Silence by not caring - it's informational and harmless; output is unaffected.

When it happens

Trigger: A program running in kitty emits an uncommon or private-mode escape sequence kitty hasn't implemented - e.g. proprietary terminal queries (some editors, tmux, IDE integrations, OSC 1337 iTerm2 extensions) or novel CSI sequences. Common during shell prompt integrations or capability probing.

Common situations: Newer shell frameworks (starship, oh-my-posh, zsh4humans) emitting shell-integration sequences, apps probing for kitty/iterm capabilities, or a garbled binary output (cat of a binary file) producing pseudo-escape sequences.

Related errors

• This must be run as kitten ask
• This should be run as kitten broadcast
• This must be run as kitten choose-files
• Pipe to kitten was broken while sending data to it
• Unknown action: {action}

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