kovidgoyal/kitty · warning

Image too large to be displayed using Unicode placeholders.

Error message

Image too large to be displayed using Unicode placeholders. Maximum size is %dx%d cells

What it means

Raised by transmit_image in the icat kitten when --place or unicode placeholder mode is requested and the image, once converted to cells, exceeds the number of available Unicode placeholder codepoints (NumberToDiacritic table length). There simply are not enough combining-character placeholders to address every cell.

Source

Thrown at kittens/icat/transmit.go:299

				// Generate a 32-bit image id using rejection sampling such that the most
				// significant byte and the two bytes in the middle are non-zero to avoid
				// collisions with applications that cannot represent non-zero most
				// significant bytes (which is represented by the third combining character)
				// or two non-zero bytes in the middle (which requires 24-bit color mode).
				imgd.image_id = next_random()
			}
			seen_image_ids.Add(imgd.image_id)
		} else {
			if len(imgd.frames) > 1 {
				for imgd.image_number == 0 {
					imgd.image_number = next_random()
				}
			}
		}
	}
	place_cursor(imgd)
	if imgd.use_unicode_placeholder && utils.Max(imgd.width_cells, imgd.height_cells) >= len(images.NumberToDiacritic) {
		imgd.err = fmt.Errorf("Image too large to be displayed using Unicode placeholders. Maximum size is %dx%d cells", len(images.NumberToDiacritic), len(images.NumberToDiacritic))
		return
	}
	switch imgd.passthrough_mode {
	case tmux_passthrough:
		imgd.err = tui.TmuxAllowPassthrough()
		if imgd.err != nil {
			return
		}
	}
	fmt.Print("\r")
	if !imgd.use_unicode_placeholder {
		if imgd.move_x_by > 0 {
			fmt.Printf("\x1b[%dC", imgd.move_x_by)
		}
		if imgd.move_to.x > 0 {
			fmt.Printf(loop.MoveCursorToTemplate, imgd.move_to.y, imgd.move_to.x)
		}
	}

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Resize the image so it fits within the max cell dimensions given in the message
2. Use a terminal with the kitty graphics protocol instead of placeholder mode
3. Split the image into smaller tiles and display each separately
4. Reduce the font-independent display size via --scale-* options

Example fix

# before
kitty +kitten icat --use-unicode-placeholders huge-scan.png
# after
kitty +kitten icat --use-unicode-placeholders --scale-height 20 huge-scan.png

const maxCells = 60 // len(images.NumberToDiacritic) in your kitty version
if widthCells >= maxCells || heightCells >= maxCells {
    // downscale image first
}

When it happens

Trigger: Using --use-unicode-placeholders (or a terminal without graphics support where icat falls back to placeholders) with an image larger than the placeholder table size in either cell dimension (width_cells or height_cells >= table length).

Common situations: Displaying very large images in terminals lacking the kitty graphics protocol, e.g. over SSH in plain terminals, with placeholder mode enabled; zoomed/scanned images rendered at full size.

Related errors

• 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
• Invalid --place specification: %s

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