kovidgoyal/kitty · error

timed out waiting for response from terminal

Error message

timed out waiting for response from terminal

What it means

query_terminal kitten sent an escape-sequence query to the terminal and did not receive a response before the timeout expired. It is thrown by main() after the read loop finishes with timed_out set, meaning the terminal never answered the query (or the answer arrived too late). Exit code 1 is returned after the partial buffer was already written to stdout.

Source

Thrown at kittens/query_terminal/main.go:75

			lp.Quit(0)
		}
		return nil
	}
	err = lp.Run()
	rc = lp.ExitCode()
	if err != nil {
		return 1, err
	}
	ds := lp.DeathSignalName()
	if ds != "" {
		fmt.Println("Killed by signal: ", ds)
		lp.KillIfSignalled()
		return
	}
	os.Stdout.WriteString(buf.String())

	if timed_out {
		return 1, fmt.Errorf("timed out waiting for response from terminal")
	}
	return
}

func EntryPoint(parent *cli.Command) {
	create_cmd(parent, main)
}

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Run inside kitty (or a terminal that implements the queried escape sequence) and verify TERM=xterm-kitty
2. Increase the query timeout if the kitten exposes a flag for it
3. Avoid running query_terminal when stdout is not a TTY; detect with os.Stdout.Stat() and ModeCharDevice
4. If under tmux/screen, set passthrough or run the query directly in kitty

if fi, _ := os.Stdout.Stat(); fi != nil && fi.Mode()&os.ModeCharDevice == 0 { return errors.New("not a terminal") }

When it happens

Trigger: Running the query_terminal kitten against a terminal emulator that does not implement the queried escape sequence (e.g. color scheme or clipboard queries), piping/redirecting output where no real terminal responds, or a very slow/locked terminal exceeding the timeout.

Common situations: Running kitty kittens over SSH without proper TERM=kitty, inside tmux/screen which swallow unknown queries, in CI, or against a non-kitty terminal that ignores the query.

Understand the failure class

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

Related errors

• Unknown marker type: {ftype}
• {rest} is not a valid marker specification
• {rest} is not a valid scroll_to_mark destination
• Timed out while waiting to read cmd response
• {name} is not a valid color

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