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.

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
• Could not get size of controlling terminal with error
• Failed to compile word_regex
• Failed to diff vs. with errors
• Left side line mismatch

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

Appendix: 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)