This terminal does not support the kitty keyboard protocol,

Error message

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.

What it means

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.

Source

Thrown at kittens/diff/main.go:188

	lp, err = loop.New()
	loop.MouseTrackingMode(lp, loop.BUTTONS_AND_DRAG_MOUSE_TRACKING)
	if err != nil {
		return 1, err
	}
	lp.ColorSchemeChangeNotifications()
	h := Handler{left: left, right: right, lp: lp}
	lp.OnInitialize = func() (string, error) {
		lp.SetCursorVisible(false)
		lp.SetCursorShape(loop.BAR_CURSOR, true)
		lp.AllowLineWrapping(false)
		lp.SetWindowTitle(fmt.Sprintf("%s vs. %s", left, right))
		lp.QueryCapabilities()
		h.initialize()
		return "", nil
	}
	lp.OnCapabilitiesReceived = func(tc loop.TerminalCapabilities) error {
		if !tc.KeyboardProtocol {
			return 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.")
		}
		h.on_capabilities_received(tc)
		return nil
	}
	lp.OnWakeup = h.on_wakeup
	lp.OnFinalize = func() string {
		lp.SetCursorVisible(true)
		lp.SetCursorShape(loop.BLOCK_CURSOR, true)
		h.finalize()
		return ""
	}
	lp.OnResize = h.on_resize
	lp.OnKeyEvent = h.on_key_event
	lp.OnText = h.on_text
	lp.OnMouseEvent = h.on_mouse_event
	err = lp.Run()
	if err != nil {
		return 1, err

View on GitHub (pinned to 6d5d0c4406)

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.

Example fix

# before (inside tmux without passthrough)
kitty +kitten diff a b

# after (tmux.conf)
set -g allow-passthrough on
# then: kitty +kitten diff a b

Defensive patterns

Strategy: validation

Validate before calling

# shell: detect multiplexer / non-kitty before launching
if [ -n "$TMUX" ] || [ -n "$STY" ]; then
    echo "run the diff kitten outside tmux/screen, or enable allow-passthrough"
    exit 1
fi
kitty +kitten diff "$@"

Type guard

// Go: kitty sets KITTY_WINDOW_ID when running under kitty
if os.Getenv("KITTY_WINDOW_ID") == "" {
    return errors.New("not running inside kitty; keyboard protocol unavailable")
}

Try / catch

Treat this as a fatal environment error: surface instructions (use kitty directly / enable tmux allow-passthrough) rather than retrying; retries will keep failing.

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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