iTerm2 "Couldn't transfer image to the terminal"

[lheinold]

I am trying to view a PDF on a rhel8 system with an ssh session open on iTerm2 (MacOS). I'm not allowed to have an x-server which is why I'm trying to view in the terminal.

I keep getting errors on any PDF I try that look like this:

Couldn't transfer image to the terminal: Error with talking to the terminal: Couldn't parse response from the terminal: The ID of type ImageId seen in the terminal response was diffeRendered: 100%

or

Couldn't transfer image to the terminal: Error with talking to the terminal: Couldn't parse response from the terminal: Terminal Response didn't start with '\x1bG' but instead 'Gi=2Rendered 100%

Note that the "Rendered 100%" cuts off the rest of the error. The rendered % goes up and down as it continuously tries to reload the PDF. The error starts as the first one but changes to the second after 1-2 reloads. The actual value after "but instead" also changes on every reload.

Note that I can actually see and read a few pages of the PDF when it's loading, and they look correct - they just constantly reload and show errors.

I'm not sure if there's an easy way to view the full error. I tried searching this github repo for the error (to see if I could find out where it was coming from) but it looks like the downstream errors might be coming from an included library.

I also tried on the "Terminal" app (instead of iTerm) - that loaded without errors but it was 100% random pixels and completely unreadable.

[lheinold]

I think I figured out what's going on but I'm not sure how to fix it (yet).

I rebuilt the project as debug and re-ran with RUST_LOG=debug, to get a debug log. I found the following:

DEBUG [tdf::kitty] Writing to kitty: "\u{1b}_Ga=T,i=1,z=-2147483647,C=1,f=24,s=842,v=1190,t=d,m=1 ...
...
DEBUG [tdf::kitty] this_err is Err(
    Transmission(
        ParsingResponse(
            IdInResponseButNotInRequest {
                ty: PlacementId,
                value: "0",
            },
        ),
    ),
)

Which means the terminal responded to image id 1 with a placement id of 0 (which wasn't specified in the request).

I turned on iTerm2 debug logging to see what it was receiving / sending and found this:

... (._Ga=T,i=1,z=-2147483647,C=1,f=24,s=842,v=1190,t=d,m=1; ...
...
1777578391.792814 PTYSession.m:3575 (-[PTYSession writeTaskImpl:encoding:forceEncoding:canBroadcast:reporting:]) main: writeTaskImpl string=ESC_Gi=1,p=0;OKESC\

Meaning that iTerm2 got the image with id 1 and responded with p=0 (which is unexpected).

It looks like iTerm2 implemented support for Kitty image transfer protocol a while ago but I'm guessing it's not "100% correct" (like it might send a placement id when it didn't actually receive one): https://gitlab.com/gnachman/iterm2/-/work_items/7825

It looks like the protocol type detection comes directly from ratataui-image, and it detects it by sending various commands and seeing if the terminal responds properly. Since iTerm2 "supports" Kitty, it responds to the initial command properly, and we detect that this is a kitty terminal (but it isn't).

Not sure how to fix this, the easiest thing to do would be to add a way to force the terminal type / protocol (with either an arg or an env variable). I haven't figured out if there's a built in way to do this yet.

[lheinold]

Update: Got it working with checkout of 2d404442739fe946cca20a9afa3d3c87f0a76b89 (Tue Jan 27 23:01:56 2026) which does not include this ratataui-image commit: ratatui/ratatui-image@cfd3349 (this commit switches from using TERM_PROGRAM to checking with IO-based detection which incorrectly detects an iterm2 terminal as a kitty-supporting terminal). TERM_PROGRAM still needs to be supplied as an env var if doing this over ssh (which I am).