kovidgoyal/kitty · warning

Screen too short, need at least 2 rows

Error message

Screen too short, need at least 2 rows

What it means

The height counterpart of the width check in Handler.render_diff: the terminal must have at least 2 rows or rendering is aborted. One row is needed for content and one for the status line, so a single-row terminal cannot display anything.

Source

Thrown at kittens/diff/ui.go:361

	if self.diff_map != nil && self.collection != nil && self.terminal_capabilities_received {
		err := self.render_diff()
		if err != nil {
			return err
		}
		if self.max_scroll_pos.Less(self.scroll_pos) {
			self.scroll_pos = self.max_scroll_pos
		}
	}
	self.draw_screen()
	return nil
}

func (self *Handler) render_diff() (err error) {
	if self.screen_size.columns < 8 {
		return fmt.Errorf("Screen too narrow, need at least 8 columns")
	}
	if self.screen_size.rows < 2 {
		return fmt.Errorf("Screen too short, need at least 2 rows")
	}
	self.logical_lines, err = render(self.collection, self.diff_map, self.screen_size, self.largest_line_number, self.images_resized_to)
	if err != nil {
		return err
	}
	last := self.logical_lines.Len() - 1
	self.max_scroll_pos.logical_line = last
	if last > -1 {
		self.max_scroll_pos.screen_line = len(self.logical_lines.At(last).screen_lines) - 1
	} else {
		self.max_scroll_pos.screen_line = 0
	}
	self.logical_lines.IncrementScrollPosBy(&self.max_scroll_pos, -self.screen_size.num_lines+1)
	if self.current_search != nil {
		self.current_search.search(self.logical_lines)
	}
	return nil
}

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Increase the window height to at least 2 rows.
2. Reduce the font size if a large font made rows effectively disappear.
3. Fix tiling layouts or tmux pane sizes that starve kitty of vertical space.

Example fix

# before
stty rows 1; kitty +kitten diff a b

# after
stty rows 24; kitty +kitten diff a b

// Go: check rows before launching
if term.IsTerminal(os.Stdout.Fd()) {
    _, h, err := term.GetSize(int(os.Stdout.Fd()))
    if err == nil && h < 2 {
        return errors.New("terminal shorter than 2 rows; increase height")
    }
}

Catch the 'Screen too short' error in resize paths, keep the previous rendered frame, and retry rendering on the next resize event once rows >=2; never propagate it as fatal.

When it happens

Trigger: Resizing the kitty window to a single row (or zero rows) while the diff kitten runs; maximizing the font size so the window fits fewer than 2 rows; embedding the kitten in a 1-row pane under tmux or a tiling WM.

Common situations: Extreme font-size increases via kitty shortcuts; tiling layouts stacking windows vertically until kitty is one line tall; scripted launches into pseudo-terminals sized 80x1.

Related errors

• Screen too narrow, need at least 8 columns
• The OS Window {os_window_id} is a panel and cannot be resize
• You must specify exactly two files/directories to compare
• The items to be diffed should both be either directories or
• This terminal does not support the kitty keyboard protocol,

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