{"record":{"id":"95646a9f9ca7c0c4","repo":"kovidgoyal/kitty","slug":"image-too-large-to-be-displayed-using-unicode-plac","errorCode":null,"errorMessage":"Image too large to be displayed using Unicode placeholders. Maximum size is %dx%d cells","messagePattern":"Image too large to be displayed using Unicode placeholders\\. Maximum size is (.+?)x(.+?) cells","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"kittens/icat/transmit.go","lineNumber":299,"sourceCode":"\t\t\t\t// Generate a 32-bit image id using rejection sampling such that the most\n\t\t\t\t// significant byte and the two bytes in the middle are non-zero to avoid\n\t\t\t\t// collisions with applications that cannot represent non-zero most\n\t\t\t\t// significant bytes (which is represented by the third combining character)\n\t\t\t\t// or two non-zero bytes in the middle (which requires 24-bit color mode).\n\t\t\t\timgd.image_id = next_random()\n\t\t\t}\n\t\t\tseen_image_ids.Add(imgd.image_id)\n\t\t} else {\n\t\t\tif len(imgd.frames) > 1 {\n\t\t\t\tfor imgd.image_number == 0 {\n\t\t\t\t\timgd.image_number = next_random()\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\tplace_cursor(imgd)\n\tif imgd.use_unicode_placeholder && utils.Max(imgd.width_cells, imgd.height_cells) >= len(images.NumberToDiacritic) {\n\t\timgd.err = fmt.Errorf(\"Image too large to be displayed using Unicode placeholders. Maximum size is %dx%d cells\", len(images.NumberToDiacritic), len(images.NumberToDiacritic))\n\t\treturn\n\t}\n\tswitch imgd.passthrough_mode {\n\tcase tmux_passthrough:\n\t\timgd.err = tui.TmuxAllowPassthrough()\n\t\tif imgd.err != nil {\n\t\t\treturn\n\t\t}\n\t}\n\tfmt.Print(\"\\r\")\n\tif !imgd.use_unicode_placeholder {\n\t\tif imgd.move_x_by > 0 {\n\t\t\tfmt.Printf(\"\\x1b[%dC\", imgd.move_x_by)\n\t\t}\n\t\tif imgd.move_to.x > 0 {\n\t\t\tfmt.Printf(loop.MoveCursorToTemplate, imgd.move_to.y, imgd.move_to.x)\n\t\t}\n\t}","sourceCodeStart":281,"sourceCodeEnd":317,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/icat/transmit.go#L281-L317","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Resize the image so it fits within the max cell dimensions given in the message","Use a terminal with the kitty graphics protocol instead of placeholder mode","Split the image into smaller tiles and display each separately","Reduce the font-independent display size via --scale-* options"],"exampleFix":"# before\nkitty +kitten icat --use-unicode-placeholders huge-scan.png\n# after\nkitty +kitten icat --use-unicode-placeholders --scale-height 20 huge-scan.png","handlingStrategy":"validation","validationCode":"const maxCells = 60 // len(images.NumberToDiacritic) in your kitty version\nif widthCells >= maxCells || heightCells >= maxCells {\n    // downscale image first\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pre-scale large images before placeholder mode","Prefer graphics-protocol terminals over placeholders"],"tags":["icat","unicode-placeholders","image-size","kitty"],"backgroundTag":"image-too-large","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}