kovidgoyal/kitty · warning

missing cached data for frame: %d

Error message

missing cached data for frame: %d

What it means

The cached metadata declares N frames but cached_data has no entry for key IMAGE_DATA_PREFIX+i for some frame i. The per-frame data files are keyed alongside the metadata, so a mismatch means the cache map is incomplete or frame keys were never populated.

Source

Thrown at kittens/choose_files/image_preview.go:104

func load_image(cached_data map[string]string) (img *images.ImageData, err error) {
	fp := cached_data[IMAGE_METADATA_KEY]
	if fp == "" {
		return nil, fmt.Errorf("missing cached image metadata")
	}
	b, err := os.ReadFile(fp)
	if err != nil {
		return nil, fmt.Errorf("failed to read cached image metadata: %w", err)
	}
	var m images.SerializableImageMetadata
	if err = json.Unmarshal(b, &m); err != nil {
		return nil, fmt.Errorf("failed to decode cached image metadata: %w", err)
	}
	frames := make([][]byte, len(m.Frames))
	for i := range m.Frames {
		path := cached_data[IMAGE_DATA_PREFIX+strconv.Itoa(i)]
		if path == "" {
			return nil, fmt.Errorf("missing cached data for frame: %d", i)
		}
		d, e := os.ReadFile(path)
		if e != nil {
			return nil, fmt.Errorf("failed to read cached image frame %d data: %w", i, e)
		}
		m.Frames[i].Size = len(d)
		frames[i] = d
	}
	return images.ImageFromSerialized(m, frames)
}

func (p *ImagePreview) ensure_source_image() (err error) {
	if p.source_img != nil {
		return
	}
	defer func() {
		if err != nil {
			p.render_err = NewErrorPreview(err)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Invalidate the cache and trigger a fresh render of the image
2. Clear the preview cache directory
3. Report/check for a kitty version mismatch in cache key format

Example fix

// before
if path == "" { return nil, fmt.Errorf("missing cached data for frame: %d", i) }
// after
if path == "" {
    invalidate_cache()
    return nil, fmt.Errorf("missing cached data for frame %d, re-rendering", i)
}

if len(m.Frames) > 0 && cached_data[IMAGE_DATA_PREFIX+"0"] == "" { /* incomplete cache, invalidate */ }

On 'missing cached data for frame' errors, invalidate the cache entry and retry the render once without cache.

When it happens

Trigger: load_image iterates m.Frames and finds an empty string for cached_data[IMAGE_DATA_PREFIX+strconv.Itoa(i)], typically after the cache was only partially populated or frame count changed.

Common situations: Animation (GIF/APNG) preview where a previous render was interrupted mid-cache-write; cache key scheme changed between kitty versions.

Related errors

• failed to read cached image metadata: %w
• failed to read cached image frame %d data: %w
• Must be run as kitten pager
• cubic-bezier easing function must have four points
• Must specify at least two points for the linear easing funct

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