kovidgoyal/kitty · warning

failed to read cached image frame %d data: %w

Error message

failed to read cached image frame %d data: %w

What it means

A frame data file whose path was stored in the cache could not be read from disk. Like error 260, this is a stale/invalid cache reference: the per-frame blob file was deleted or is unreadable while the metadata still references it.

Source

Thrown at kittens/choose_files/image_preview.go:108

		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)
		}
	}()
	p.source_img, err = load_image(p.cached_data)
	return

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Invalidate the cache entry and re-render from the source image
2. Verify the cache directory is persistent and writable for kitty's lifetime
3. Check disk space and permissions on the cache location

Example fix

// before
d, e := os.ReadFile(path)
// after
d, e := os.ReadFile(path)
if e != nil { invalidate_cache(); return nil, fmt.Errorf("frame %d cache unreadable, re-render: %w", i, e) }

for _, p := range framePaths { if _, err := os.Stat(p); err != nil { invalidate cache } }

errors.Is(err, fs.ErrNotExist) || errors.Is(err, fs.ErrPermission) -> drop cache and re-render.

When it happens

Trigger: os.ReadFile(path) fails for a frame data file inside load_image's frame loop, called from RenderImagePreview/ensure_source_image.

Common situations: Cache cleanup jobs removing frame blobs; disk full or permission changes; container/sandbox environments with ephemeral temp dirs.

Related errors

• failed to read cached image metadata: %w
• missing cached data for frame: %d
• No cache found and max cache age is negative
• failed to decode cached image metadata: %w
• failed to read the directory %s with error: %w

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