{"record":{"id":"a9f92a1a1f55f674","repo":"kovidgoyal/kitty","slug":"this-terminal-does-not-support-the-kitty-keyboard","errorCode":null,"errorMessage":"This terminal does not support the kitty keyboard protocol, or you are running inside a terminal multiplexer that is blocking querying for kitty keyboard protocol support. The diff kitten cannot function without it.","messagePattern":"This terminal does not support the kitty keyboard protocol, or you are running inside a terminal multiplexer that is blocking querying for kitty keyboard protocol support\\. The diff kitten cannot function without it\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kittens/diff/main.go","lineNumber":188,"sourceCode":"\tlp, err = loop.New()\n\tloop.MouseTrackingMode(lp, loop.BUTTONS_AND_DRAG_MOUSE_TRACKING)\n\tif err != nil {\n\t\treturn 1, err\n\t}\n\tlp.ColorSchemeChangeNotifications()\n\th := Handler{left: left, right: right, lp: lp}\n\tlp.OnInitialize = func() (string, error) {\n\t\tlp.SetCursorVisible(false)\n\t\tlp.SetCursorShape(loop.BAR_CURSOR, true)\n\t\tlp.AllowLineWrapping(false)\n\t\tlp.SetWindowTitle(fmt.Sprintf(\"%s vs. %s\", left, right))\n\t\tlp.QueryCapabilities()\n\t\th.initialize()\n\t\treturn \"\", nil\n\t}\n\tlp.OnCapabilitiesReceived = func(tc loop.TerminalCapabilities) error {\n\t\tif !tc.KeyboardProtocol {\n\t\t\treturn fmt.Errorf(\"This terminal does not support the kitty keyboard protocol, or you are running inside a terminal multiplexer that is blocking querying for kitty keyboard protocol support. The diff kitten cannot function without it.\")\n\t\t}\n\t\th.on_capabilities_received(tc)\n\t\treturn nil\n\t}\n\tlp.OnWakeup = h.on_wakeup\n\tlp.OnFinalize = func() string {\n\t\tlp.SetCursorVisible(true)\n\t\tlp.SetCursorShape(loop.BLOCK_CURSOR, true)\n\t\th.finalize()\n\t\treturn \"\"\n\t}\n\tlp.OnResize = h.on_resize\n\tlp.OnKeyEvent = h.on_key_event\n\tlp.OnText = h.on_text\n\tlp.OnMouseEvent = h.on_mouse_event\n\terr = lp.Run()\n\tif err != nil {\n\t\treturn 1, err","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/diff/main.go#L170-L206","documentation":"After starting its event loop, the diff kitten queries the terminal for capabilities and requires the kitty keyboard protocol. If the terminal does not answer positively (or a multiplexer like tmux/screen intercepts or swallows the query), the OnCapabilitiesReceived callback returns this error and the kitten aborts. The diff kitten's keybindings rely on kitty keyboard protocol escape codes to function.","triggerScenarios":"Running the diff kitten inside tmux or screen without pass-through of escape sequences; running it in a non-kitty terminal (xterm, gnome-terminal, alacritty without kitty keyboard support); SSH connections where the query response is dropped; a terminal that responds to CSI ? u queries incorrectly.","commonSituations":"Users on tmux older than 3.3 (no allow-passthrough) or with it disabled; running kitty itself inside another multiplexer; using a terminal emulator that predates adoption of the kitty keyboard protocol; old SSH/expect wrappers eating the DCS reply.","solutions":["Run the diff kitten in a real kitty window, not inside tmux/screen.","If you must use tmux, upgrade to >=3.3 and set `set -g allow-passthrough on`.","If using another terminal, verify it supports the kitty keyboard protocol; otherwise switch to kitty for diffing.","Check that TERM is not being overwritten to something that disables the queries."],"exampleFix":"# before (inside tmux without passthrough)\nkitty +kitten diff a b\n\n# after (tmux.conf)\nset -g allow-passthrough on\n# then: kitty +kitten diff a b","handlingStrategy":"validation","validationCode":"# shell: detect multiplexer / non-kitty before launching\nif [ -n \"$TMUX\" ] || [ -n \"$STY\" ]; then\n    echo \"run the diff kitten outside tmux/screen, or enable allow-passthrough\"\n    exit 1\nfi\nkitty +kitten diff \"$@\"","typeGuard":"// Go: kitty sets KITTY_WINDOW_ID when running under kitty\nif os.Getenv(\"KITTY_WINDOW_ID\") == \"\" {\n    return errors.New(\"not running inside kitty; keyboard protocol unavailable\")\n}","tryCatchPattern":"Treat this as a fatal environment error: surface instructions (use kitty directly / enable tmux allow-passthrough) rather than retrying; retries will keep failing.","preventionTips":["Launch the kitten from real kitty windows.","Keep tmux >=3.3 with allow-passthrough on if nesting is unavoidable.","Check KITTY_WINDOW_ID / TERM=xterm-kitty in wrappers before invoking."],"tags":["kitty","diff-kitten","terminal-capabilities","keyboard-protocol","tmux"],"backgroundTag":"terminal-capability-query-failed","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}