kovidgoyal/kitty · error

This terminal does not support the graphics protocol use a t

Error message

This terminal does not support the graphics protocol use a terminal such as kitty, WezTerm or Konsole that does. If you are running inside a terminal multiplexer such as tmux or screen that might be interfering as well.

What it means

icat probed the terminal for the kitty graphics protocol and did not detect direct support. Only terminals speaking the graphics protocol (kitty, WezTerm, Konsole, recent Ghostty) can display images this way; multiplexers like tmux/screen can also mask it.

Source

Thrown at kittens/icat/main.go:292

	passthrough_mode := no_passthrough
	switch opts.Passthrough {
	case "tmux":
		passthrough_mode = tmux_passthrough
	case "detect":
		if tui.TmuxSocketAddress() != "" {
			passthrough_mode = tmux_passthrough
		}
	}

	if passthrough_mode == no_passthrough && (opts.TransferMode == "detect" || opts.DetectSupport) {
		memory, files, direct, err := DetectSupport(time.Duration(opts.DetectionTimeout * float64(time.Second)))
		if err != nil {
			return 1, err
		}
		if !direct {
			keep_going.Store(false)
			return 1, fmt.Errorf("This terminal does not support the graphics protocol use a terminal such as kitty, WezTerm or Konsole that does. If you are running inside a terminal multiplexer such as tmux or screen that might be interfering as well.")
		}
		if memory {
			transfer_by_memory = supported
		} else {
			transfer_by_memory = unsupported
		}
		if files {
			transfer_by_file = supported
		} else {
			transfer_by_file = unsupported
		}
	}
	if passthrough_mode != no_passthrough {
		// tmux doesn't allow responses from the terminal so we can't detect if memory or file based transferring is supported
		transfer_by_memory = unsupported
		transfer_by_file = unsupported
	}
	if opts.DetectSupport {

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Run directly in kitty/WezTerm/Konsole/Ghostty
2. Set TERM=xterm-kitty (and correct TERMINFO) when inside kitty
3. Increase --detect-support-timeout on slow links
4. For tmux, ensure a recent tmux with allow-passthrough or run outside it

Example fix

# before (inside tmux)
kitten icat img.png
# after
tmux detach
kitten icat img.png

env := os.Getenv("KITTY_WINDOW_ID")
if env == "" && os.Getenv("TERM") != "xterm-kitty" { /* fall back to plain cat or chafa */ }

err := cmd.Run()
if err != nil && strings.Contains(err.Error(), "graphics protocol") { /* fallback renderer */ }

When it happens

Trigger: DetectSupport() times out (controlled by --detect-support-timeout) or the terminal doesn't answer the graphics query, so direct == false.

Common situations: Running in tmux/screen (default tmux doesn't forward the queries); TERM set wrongly; slow SSH link where the probe times out; very old terminal emulator.

Related errors

• Timed out waiting for a response from the terminal: %w
• Terminal does not support reporting screen sizes in pixels,
• Invalid value for --background: %w
• Invalid value for --z-index with error: %w
• unknown fit specification: %#v

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