kovidgoyal/kitty · error

Failed to query terminal using TIOCGWINSZ with error: %w

Error message

Failed to query terminal using TIOCGWINSZ with error: %w

What it means

After obtaining a tty fd (stdout fd or /dev/tty), the TIOCGWINSZ ioctl to read window size failed. The open succeeded but the size query itself returned an error.

Source

Thrown at kittens/icat/main.go:190

	if err != nil {
		return 1, err
	}
	err = parse_mirror()
	if err != nil {
		return 1, err
	}
	if opts.UseWindowSize == "" {
		if tty.IsTerminal(os.Stdout.Fd()) {
			screen_size, err = tty.GetSize(int(os.Stdout.Fd()))
		} else {
			t, oerr := tty.OpenControllingTerm()
			if oerr != nil {
				return 1, fmt.Errorf("Failed to open controlling terminal with error: %w", oerr)
			}
			screen_size, err = t.GetSize()
		}
		if err != nil {
			return 1, fmt.Errorf("Failed to query terminal using TIOCGWINSZ with error: %w", err)
		}
	} else {
		parts := strings.SplitN(opts.UseWindowSize, ",", 4)
		if len(parts) != 4 {
			return 1, fmt.Errorf("Invalid size specification: %s", opts.UseWindowSize)
		}
		screen_size = &unix.Winsize{}
		var t uint64
		if t, err = strconv.ParseUint(parts[0], 10, 16); err != nil || t < 1 {
			return 1, fmt.Errorf("Invalid size specification: %s with error: %w", opts.UseWindowSize, err)
		}
		screen_size.Col = uint16(t)
		if t, err = strconv.ParseUint(parts[1], 10, 16); err != nil || t < 1 {
			return 1, fmt.Errorf("Invalid size specification: %s with error: %w", opts.UseWindowSize, err)
		}
		screen_size.Row = uint16(t)
		if t, err = strconv.ParseUint(parts[2], 10, 16); err != nil || t < 1 {
			return 1, fmt.Errorf("Invalid size specification: %s with error: %w", opts.UseWindowSize, err)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Run with stdout connected to the kitty terminal
2. Pass --use-window-size with an explicit W,H,cell_w,cell_h spec instead
3. Retry in a fresh terminal if the pty was closed mid-session

Example fix

# before
kitty +kitten icat img.png | tee log
# after
kitty +kitten icat --use-window-size 120,32,7,14 img.png | tee log

ws, err := tty.GetSize(fd)
if err != nil && !tty.IsTerminal(fd) { /* use explicit --use-window-size */ }

Wrap GetSize; on failure retry once, then fall back to a --use-window-size spec or sane defaults.

When it happens

Trigger: The opened fd does not refer to a terminal device (e.g. redirected fd, pty closed mid-run), so ioctl fails with ENOTTY/EINVAL.

Common situations: stdout redirected to a file while /dev/tty resolves to something non-queryable; race where the pty closes; exotic terminal multiplexers.

Related errors

• Failed to open controlling terminal with error: %w
• Timed out waiting for a response from the terminal: %w
• 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/6ee91f5fe6c0ea33. Report an issue: GitHub.