kovidgoyal/kitty · warning

Screen too narrow, need at least 8 columns

Error message

Screen too narrow, need at least 8 columns

What it means

Before rendering, Handler.render_diff verifies the terminal is at least 8 columns wide. kitty sends resize events to the kitten, and when the window/pane becomes narrower than 8 columns the render is aborted with this error. The minimum exists because the diff layout (line numbers, margins, separators) cannot fit below that width.

Source

Thrown at kittens/diff/ui.go:358

func (self *Handler) on_resize(old_size, new_size loop.ScreenSize) error {
	self.clear_mouse_selection()
	self.update_screen_size(new_size)
	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)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Widen the kitty window to at least 8 columns and rerun/reopen the kitten.
2. If using a tiling WM or splits, give the kitty window more horizontal space.
3. Avoid launching the diff kitten from scripts in pseudo-terminals with fixed tiny COLUMNS.

Example fix

# before
kitty +kitten diff a b   # window only 4 columns wide

# after
# resize window >= 8 columns, then
kitty +kitten diff a b

// Go: check terminal size before launching the kitten
if term.IsTerminal(os.Stdout.Fd()) {
    w, _, err := term.GetSize(int(os.Stdout.Fd()))
    if err == nil && w < 8 {
        return errors.New("terminal narrower than 8 columns; widen the window")
    }
}

In on_resize handlers, if render_diff returns 'Screen too narrow', skip rendering and show a placeholder frame; re-render automatically when the next resize event reports >=8 columns.

When it happens

Trigger: Resizing the kitty window below 8 columns while the diff kitten is open; splitting the kitty OS window into many tabs/OS-windows so each falls under 8 columns; opening the kitten in a tiny embedded window or with a huge font size in a minimal window; automated screenshot/tmux environments with tiny pseudo-terminals.

Common situations: Accidental ultra-narrow resize during use; tiling window manager layouts squeezing kitty to a sliver; font size increases (ctrl+shift+plus) shrinking effective column count below the minimum.

Related errors

• Screen too short, need at least 2 rows
• 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/c75d35822112099b. Report an issue: GitHub.