yorukot/superfile · error

failed to encode kitty graphics: %w

Error message

failed to encode kitty graphics: %w

What it means

This error wraps a failure from the underlying Kitty graphics encoder while building the command for the image (columns, rows, virtual placement, chunking). The kitty graphics encoder returned an error while producing the transmission payload for the rendered image. The image itself decoded fine; serialization into the Kitty protocol failed.

Source

Thrown at src/pkg/file_preview/kitty.go:129

	var transmitBuf bytes.Buffer

	// Delete previous image with this ID first
	transmitBuf.WriteString(ansi.KittyGraphics(nil, fmt.Sprintf("a=d,d=i,i=%d", imgID)))

	if err := kitty.EncodeGraphics(&transmitBuf, img, &kitty.Options{
		ID:               imgID,
		Action:           kitty.TransmitAndPut,
		Transmission:     kitty.Direct,
		Format:           kitty.RGBA,
		ImageWidth:       imgArea.Dx(),
		ImageHeight:      imgArea.Dy(),
		Columns:          dstCols,
		Rows:             dstRows,
		VirtualPlacement: true,
		Quite:            kittyQuietAll,
		Chunk:            true,
	}); err != nil {
		return nil, fmt.Errorf("failed to encode kitty graphics: %w", err)
	}

	// Build Unicode placeholder cells for the view
	placeholders := buildKittyPlaceholders(imgID, dstCols, dstRows)

	return &KittyImageResult{
		Placeholders: placeholders,
		RawTransmit:  transmitBuf.String(),
	}, nil
}

// buildKittyPlaceholders builds a string of Kitty Unicode placeholder characters
// that the terminal replaces with the transmitted image.
func buildKittyPlaceholders(imgID int, cols, rows int) string {
	// Encode image ID as foreground color for the placeholder cells.
	// The terminal uses this color to identify which image to display.
	r, g, b := byte((imgID>>rgbShift16)&rgbMask), byte((imgID>>rgbShift8)&rgbMask), byte(imgID&rgbMask)

View on GitHub (pinned to b72f550bc6)

Solutions

1. Inspect the wrapped cause with errors.Unwrap / %v of the returned error to see the encoder's actual complaint.
2. Verify the image decoded to a valid non-empty image.Image before calling the renderer.
3. Confirm dstCols/dstRows derived from maxWidth/maxHeight are positive and sane (see error 60's guard upstream).
4. Update/patch the kitty encoder dependency; if the bug persists, fall back to the standard cell-based image renderer (e.g. sixel or block-art fallback).

Example fix

// before
res, err := previewer.ImagePreviewWithRenderer(img, path, w, h)
// after
res, err := previewer.ImagePreviewWithRenderer(img, path, w, h)
if err != nil {
    log.Debugf("kitty render failed: %v, falling back", err)
    res, err = previewer.renderFallback(img, path, w, h)
}

if img == nil { return errors.New("nil image, skipping kitty render") }
if w <= 0 || h <= 0 { return errors.New("invalid dimensions for kitty render") }

res, err := previewer.ImagePreviewWithRenderer(img, path, w, h)
if err != nil {
    var encErr error
    if errors.Unwrap(err) != nil { encErr = errors.Unwrap(err) }
    log.Warnf("kitty encode failed (%v); using fallback renderer", encErr)
    res, err = fallbackRenderer(img, path, w, h)
}

When it happens

Trigger: Calling renderWithKittyUsingTermCap when the kitty encode step rejects the command parameters or cannot serialize the image payload — e.g. oversized image data for the chunking scheme, an invalid image ID/placement combination, or an internal encoder error surfaced from the kitty library call.

Common situations: Very large images exceeding protocol/chunk limits; corrupted or partially decoded images passed downstream; misconfigured encoder options; regression after changing dstCols/dstRows computation so rows/cols are 0 or negative.

Related errors

• dimensions must be positive (maxWidth=%d, maxHeight=%d)
• error encoding data : %w

AI-assisted analysis of yorukot/superfile@b72f550bc6 (2026-09-01). Data as JSON: /api/errors/33c685128b77c093. Report an issue: GitHub.