What causes "Failed to render the preview with error: %w" in kovidgoyal/kitty?

Inspect the wrapped inner error to find the real cause (decode failure vs tooling missing)

Failed to render the preview with error: %w

Error message

Failed to render the preview with error: %w

What it means

The asynchronous image rendering goroutine reported an error, which Render wraps as 'Failed to render the preview with error'. The underlying hd.err comes from the actual image decode/render pipeline (e.g. unsupported format, ffmpeg failure for videos, OOM on huge images).

Source

Thrown at kittens/choose_files/image_preview.go:162

}

func (p *ImagePreview) Render(h *Handler, x, y, width, height int) {
	if p.render_channel == nil {
		if p.render_err == nil {
			p.render_image(h, x, y, width, height)
		} else {
			p.render_err.Render(h, x, y, width, height)
		}
		return
	}
	select {
	case hd := <-p.render_channel:
		p.render_channel = nil
		p.cached_data = hd.cached_data
		p.source_img = hd.img
		p.custom_metadata = hd.metadata
		if hd.err != nil {
			p.render_err = NewFileMetadataPreviewWithError(p.abspath, p.metadata, fmt.Errorf("Failed to render the preview with error: %w", hd.err))
		}
		p.Render(h, x, y, width, height)
		return
	default:
	}
	if p.file_metadata_preview == nil {
		p.file_metadata_preview = NewFileMetadataPreview(p.abspath, p.metadata)
		m := p.file_metadata_preview.(*MessagePreview)
		m.trailers = append(m.trailers, "", "Rendering image preview, please wait…")
	}
	p.file_metadata_preview.Render(h, x, y, width, height)
}

func (p *ImagePreview) start_rendering() {
	defer func() {
		if r := recover(); r != nil {
			p.render_channel <- render_data{err: parallel.Format_stacktrace_on_panic(r, 1)}
		}

View on GitHub (pinned to 6d5d0c4406)

Solutions

Inspect the wrapped inner error to find the real cause (decode failure vs tooling missing)
Verify the source file is a valid supported image (or that ffmpeg exists for video)
Update kitty / reinstall missing image-format support

Example fix

// before
p.render_err = NewFileMetadataPreviewWithError(p.abspath, p.metadata, fmt.Errorf("Failed to render the preview with error: %w", hd.err))
// after (surface inner cause clearly)
log.Printf("preview render failed for %s: %v", p.abspath, hd.err)
p.render_err = NewFileMetadataPreviewWithError(p.abspath, p.metadata, fmt.Errorf("Failed to render the preview with error: %w", hd.err))

Defensive patterns

Strategy: try-catch

Try / catch

Capture hd.err, log it, and degrade gracefully to a text metadata preview instead of crashing the chooser.

Prevention

Pre-validate that the file is a decodable image before previewing
Ensure ffmpeg is installed when video previews are enabled

When it happens

Trigger: Render receives from p.render_channel with hd.err != nil after start_rendering's worker failed; the preview is replaced with an error FileMetadataPreview.

Common situations: Previewing a corrupt or unsupported image/video; missing ffmpeg for video previews; extremely large images exceeding memory limits.

Related errors

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