What causes "Failed to read image data output file: %s with error: %w" in kovidgoyal/kitty?

Re-run icat on the original image file directly

Failed to read image data output file: %s with error: %w

Error message

Failed to read image data output file: %s with error: %w

What it means

Raised by transmit_stream in the icat kitten when the frame's image file must be read from disk (no in-memory bytes exist) and os.ReadFile fails. This happens when the cached/processed image output file was deleted or became unreadable between processing and transmission.

Source

Thrown at kittens/icat/transmit.go:161

			os.Remove(f.Name())
			return fmt.Errorf("Failed to write image data to temp file for transmission: %w", err)
		}
		fname = f.Name()
	}
	gc := gc_for_image(imgd, frame_num, frame)
	gc.SetTransmission(utils.IfElse(is_temp, graphics.GRT_transmission_tempfile, graphics.GRT_transmission_file))
	if data_size > 0 {
		gc.SetDataSize(uint64(data_size))
	}
	return gc.WriteWithPayloadTo(os.Stdout, utils.UnsafeStringToBytes(fname))
}

func transmit_stream(imgd *image_data, frame_num int, frame *image_frame) (err error) {
	data := frame.in_memory_bytes
	if data == nil {
		data, err = os.ReadFile(frame.filename)
		if err != nil {
			return fmt.Errorf("Failed to read image data output file: %s with error: %w", frame.filename, err)
		}
	}
	gc := gc_for_image(imgd, frame_num, frame)
	return gc.WriteWithPayloadTo(os.Stdout, data)
}

func calculate_in_cell_x_offset(width, cell_width int) int {
	extra_pixels := width % cell_width
	if extra_pixels == 0 {
		return 0
	}
	switch opts.Align {
	case "left":
		return 0
	case "right":
		return cell_width - extra_pixels
	default:
		return (cell_width - extra_pixels) / 2

View on GitHub (pinned to 6d5d0c4406)

Solutions

Re-run icat on the original image file directly
Check that the kitty cache directory is not being pruned by tmp cleaners; exclude it from systemd-tmpfiles
Verify read permissions on the file shown in the error message
Avoid pointing kitty cache at volatile storage like /tmp with aggressive cleanup

Defensive patterns

Strategy: retry

Validate before calling

if _, err := os.Stat(frameFilename); err != nil {
    // re-generate the image file before transmission
}

Try / catch

if err := transmit(); err != nil {
    if strings.Contains(err.Error(), "Failed to read image data") {
        regenerateImage() // then retry once
    }
}

Prevention

Exclude kitty cache dirs from tmp cleaners
Avoid caching on volatile storage

When it happens

Trigger: Running icat in stream mode where frame.in_memory_bytes is nil and frame.filename no longer exists or is not readable. Commonly a race where a cache file was cleaned up, or permissions changed while the kitten ran.

Common situations: Cache directories cleaned mid-run, NFS/tmp-reaper (systemd-tmpfiles) removing files, running icat over a file on an unmounted/rotated network share.

Related errors

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