kovidgoyal/kitty · warning

failed to decode cached image metadata: %w

Error message

failed to decode cached image metadata: %w

What it means

The cached image metadata file was read successfully but its contents are not valid JSON matching images.SerializableImageMetadata. This happens when the cache file was truncated (crash during write) or written by an incompatible kitty version with a different schema.

Source

Thrown at kittens/choose_files/image_preview.go:98

func (p *ImagePreview) IsValidForColorScheme(bool) bool { return true }
func (p *ImagePreview) IsReady() bool                   { return p.ready.Load() || p.render_channel == nil }

func (p *ImagePreview) Unload() {
	p.source_img = nil
}

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) {

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Invalidate the cache entry and re-render the image from the original file
2. Clear kitty's preview cache directory
3. Ensure all machines/instances sharing a cache run the same kitty version

Example fix

// before
if err = json.Unmarshal(b, &m); err != nil { return nil, err }
// after
if err = json.Unmarshal(b, &m); err != nil {
    os.Remove(fp) // invalidate corrupt cache
    return nil, fmt.Errorf("corrupt cache, re-render needed: %w", err)
}

if err := json.Unmarshal(b, &m); err != nil { os.Remove(fp); re-render from source image }

When it happens

Trigger: json.Unmarshal of the cached metadata file fails inside load_image, invoked via RenderImagePreview or ensure_source_image.

Common situations: Kitty upgraded changing SerializableImageMetadata fields; partial write due to a killed kitten process; cache corruption.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to read cached image metadata: %w
• missing cached data for frame: %d
• failed to read cached image frame %d data: %w
• Could not encode message to kitty with error: %w
• Failed to load output from custom processor %#v with error:

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