kovidgoyal/kitty · error

Timed out waiting for a response from the terminal: %w

Error message

Timed out waiting for a response from the terminal: %w

What it means

icat sends a graphics query to the terminal and arms a one-shot timer on the event loop; if the terminal never responds within the timeout, the timer returns this error wrapping os.ErrDeadlineExceeded.

Source

Thrown at kittens/icat/detect.go:49

	}

	defer func() {
		if len(temp_files_to_delete) > 0 && transfer_by_file != supported {
			for _, name := range temp_files_to_delete {
				os.Remove(name)
			}
		}
		if len(shm_files_to_delete) > 0 && transfer_by_memory != supported {
			for _, name := range shm_files_to_delete {
				_ = name.Unlink()
			}
		}
	}()

	lp.OnInitialize = func() (string, error) {
		var iid uint32
		_, _ = lp.AddTimer(timeout, false, func(loop.IdType) error {
			return fmt.Errorf("Timed out waiting for a response from the terminal: %w", os.ErrDeadlineExceeded)
		})

		g := func(t graphics.GRT_t, payload string) uint32 {
			iid += 1
			g1 := &graphics.GraphicsCommand{}
			g1.SetTransmission(t).SetAction(graphics.GRT_action_query).SetImageId(iid).SetDataWidth(1).SetDataHeight(1).SetFormat(
				graphics.GRT_format_rgb).SetDataSize(uint64(len(payload)))
			_ = g1.WriteWithPayloadToLoop(lp, utils.UnsafeStringToBytes(payload))
			return iid
		}

		direct_query_id = g(graphics.GRT_transmission_direct, "123")
		tf, err := images.CreateTempInRAM()
		if err == nil {
			file_query_id = g(graphics.GRT_transmission_tempfile, tf.Name())
			temp_files_to_delete = append(temp_files_to_delete, tf.Name())
			if _, err = tf.Write([]byte{1, 2, 3}); err != nil {
				print_error("Failed to write to temporary file for data transfer, file based transfer is disabled. Error: %v", err)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Run inside a terminal supporting the kitty graphics protocol (kitty itself, or a compatible terminal)
2. Detach from tmux/screen or configure passthrough so escape sequences reach the outer terminal
3. Increase the timeout if the terminal is slow, or pre-check protocol support

Example fix

# before
$ tmux
$ kitty +kitten icat img.png
# after: run directly in kitty, or set passthrough
$ kitty +kitten icat img.png

if !supportsGraphicsProtocol() { /* skip query, render without graphics */ }

On os.ErrDeadlineExceeded from the query, fall back to plain text output or retry once with a longer timeout.

When it happens

Trigger: Running icat against a terminal that doesn't support the kitty graphics protocol (so no query response), or a slow/overloaded terminal that misses the timeout window.

Common situations: Running kitty +kitten icat inside tmux/screen without proper passthrough, over ssh with a non-kitty terminal, or inside a plain Linux VT.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• This terminal does not support the graphics protocol use a t
• Timed out while waiting to read cmd response
• 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/1540b03ea53d4f19. Report an issue: GitHub.