Kitty Graphics Troubleshooting

This page helps when a program shows images through the Kitty graphics protocol and something is wrong. It needs Nash 0.8.1 or newer. Older builds do not include the placement fixes and capability replies that the steps below assume.

Read the reason first

Nash does not send an error reply to the program when an image command fails. It writes the reason to its log instead, on a line that starts with kitty_img:.

Reproduce the problem.
Press CTRL+SHIFT+L to open the debug overlay. It lists the most recently logged problems.
Look for a line that starts with kitty_img:.
Match the message against the table in the next section.

For more detail, start Nash from a shell with NASH_LOG=debug nash. The output goes to that shell. Log files are in $XDG_RUNTIME_DIR/nash on Unix systems, or in $HOME/.local/share/nash on macOS and Windows.

A program says Nash has no image support

Programs detect support with a capability query. Nash answers a query with OK, unless Kitty graphics is turned off.

Run nash --version and check that it is 0.8.1 or newer.
Look for a custom.lua file in your Nash configuration directory (~/.config/nash by default). If it sets enable_kitty_graphics = false, Nash ignores every Kitty graphics sequence, including queries, and sends no reply.
If the program runs in tmux, the query and the reply must pass through tmux. Check your tmux passthrough settings.

The upload works but nothing appears

Log message after `kitty_img:`	Meaning and next step
`refusing to display image: terminal has no cell pixel dimensions`	The pane reports no pixel size, so Nash cannot compute how many cells the image covers. Nash refuses the image instead of guessing. Compare with a plain local pane.
`Ignoring image data for image with dimensions ...`	The decoded RGBA data is larger than 100 MB, about 25 million pixels. Scale the image down before you send it.
`Ignoring image with 0x0 dimensions`	The image has no pixels. Check the file.
`refusing to display image with zero draw dimensions`	The program asked for an empty source rectangle (`w=0` or `h=0`), or an origin (`x=`, `y=`) outside the image.
`missing width/height info for kitty img`	A raw RGB or RGBA upload (`f=24` or `f=32`) has no `s=` and `v=`.
`transmit data len is ... but it doesn't match widthheight4`	The data length does not match the pixel size. Check the program's size keys.
`cannot use both i= and I= in the same request`	The upload set an image id and an image number. A request can have one of them.
`data should have been materialized in coalesce_kitty_accumulation`	Nash could not read or decode the payload: a file or shared memory object (`t=f`, `t=t`, `t=s`) that it cannot open, or invalid base64 data. The message ends with the cause.
`no matching image id ... in id_to_data`	A placement refers to an image that Nash does not hold. See below.

A placement refers to a missing image

Nash can lack the image for these reasons:

The program deleted it with an uppercase delete (d=I and similar) or replaced it with new data.
The image belongs to the other screen. The primary screen and the alternate screen keep separate images.
Stored image data went over the fixed budget of 320 MiB, and Nash freed the images that no placement or placeholder used.

The program runs on a remote machine

A t=f, t=t, or t=s upload names a file or shared memory object. Nash opens it on your machine, but the program names a path on the remote machine. Configure the program to send the image data directly (t=d).

An image shows, then disappears

clear, and any program that sends ED 2, removes the placements on the screen. This is the intended behavior.
A full-screen program uses the alternate screen. When it exits, you see the images of the primary screen again, not its own.
A program can delete its images with a=d. See the delete modes in Kitty Graphics Protocol.
An image with a z-index below -1073741824 is drawn beneath cell backgrounds. A cell with a non-default background color hides it.

The image has the wrong size

Without c= and r=, Nash draws the image at its pixel size.
With only c= or only r=, Nash computes the other value and keeps the aspect ratio of the source area.
With both, the image stretches to fill the cells. Ask the program to set only one of them if the picture looks squashed.
An X= or Y= offset moves the image inside its first cell. It is part of the area that c= and r= describe.

Text draws over the image

After a placement, the cursor moves to the last row of the image, after its last column. With C=1, the cursor stays where it was, at the top left of the image, so the next text prints over the image. Images with a negative z-index stay beneath the text, so the text remains readable.

Images are missing after an upgrade in a multiplexer session

Nash 0.8.1 raised the multiplexer protocol to version 48. A multiplexer server that speaks an older version cannot serve the new window. The window shows advice when it fails to attach for this reason.

Run nash mux status. It shows the protocol version of the server and of your build.
Save your work in the panes that the server owns.
Run nash mux restart when you can close those panes.

nash mux restart closes every pane the server owns. nash update and nash mux update never restart the server, so a running server keeps its old protocol until you restart it. See Multiplexer.

Still stuck?

Collect these items before you ask for help:

The output of nash --version.
The kitty_img: lines from the debug overlay or the log.
The name and version of the program that shows the images.
Whether the program runs in tmux, over SSH, or in a multiplexer session.