{"record":{"id":"33c685128b77c093","repo":"yorukot/superfile","slug":"failed-to-encode-kitty-graphics-w","errorCode":null,"errorMessage":"failed to encode kitty graphics: %w","messagePattern":"failed to encode kitty graphics: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/pkg/file_preview/kitty.go","lineNumber":129,"sourceCode":"\tvar transmitBuf bytes.Buffer\n\n\t// Delete previous image with this ID first\n\ttransmitBuf.WriteString(ansi.KittyGraphics(nil, fmt.Sprintf(\"a=d,d=i,i=%d\", imgID)))\n\n\tif err := kitty.EncodeGraphics(&transmitBuf, img, &kitty.Options{\n\t\tID:               imgID,\n\t\tAction:           kitty.TransmitAndPut,\n\t\tTransmission:     kitty.Direct,\n\t\tFormat:           kitty.RGBA,\n\t\tImageWidth:       imgArea.Dx(),\n\t\tImageHeight:      imgArea.Dy(),\n\t\tColumns:          dstCols,\n\t\tRows:             dstRows,\n\t\tVirtualPlacement: true,\n\t\tQuite:            kittyQuietAll,\n\t\tChunk:            true,\n\t}); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to encode kitty graphics: %w\", err)\n\t}\n\n\t// Build Unicode placeholder cells for the view\n\tplaceholders := buildKittyPlaceholders(imgID, dstCols, dstRows)\n\n\treturn &KittyImageResult{\n\t\tPlaceholders: placeholders,\n\t\tRawTransmit:  transmitBuf.String(),\n\t}, nil\n}\n\n// buildKittyPlaceholders builds a string of Kitty Unicode placeholder characters\n// that the terminal replaces with the transmitted image.\nfunc buildKittyPlaceholders(imgID int, cols, rows int) string {\n\t// Encode image ID as foreground color for the placeholder cells.\n\t// The terminal uses this color to identify which image to display.\n\tr, g, b := byte((imgID>>rgbShift16)&rgbMask), byte((imgID>>rgbShift8)&rgbMask), byte(imgID&rgbMask)\n","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/yorukot/superfile/blob/b72f550bc6e75913f48eb49fdd258e1a2df2fe88/src/pkg/file_preview/kitty.go#L111-L147","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped cause with errors.Unwrap / %v of the returned error to see the encoder's actual complaint.","Verify the image decoded to a valid non-empty image.Image before calling the renderer.","Confirm dstCols/dstRows derived from maxWidth/maxHeight are positive and sane (see error 60's guard upstream).","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)."],"exampleFix":"// before\nres, err := previewer.ImagePreviewWithRenderer(img, path, w, h)\n// after\nres, err := previewer.ImagePreviewWithRenderer(img, path, w, h)\nif err != nil {\n    log.Debugf(\"kitty render failed: %v, falling back\", err)\n    res, err = previewer.renderFallback(img, path, w, h)\n}","handlingStrategy":"try-catch","validationCode":"if img == nil { return errors.New(\"nil image, skipping kitty render\") }\nif w <= 0 || h <= 0 { return errors.New(\"invalid dimensions for kitty render\") }","typeGuard":null,"tryCatchPattern":"res, err := previewer.ImagePreviewWithRenderer(img, path, w, h)\nif err != nil {\n    var encErr error\n    if errors.Unwrap(err) != nil { encErr = errors.Unwrap(err) }\n    log.Warnf(\"kitty encode failed (%v); using fallback renderer\", encErr)\n    res, err = fallbackRenderer(img, path, w, h)\n}","preventionTips":["Always keep a non-kitty fallback renderer for terminals/libraries where encoding fails.","Validate decoded images are non-nil and reasonably sized before rendering.","Pin and test against the kitty encoder dependency version in CI.","Log the unwrapped cause, not just the wrapper, to diagnose encoder issues."],"tags":["kitty","graphics-protocol","encoding","image-preview"],"backgroundTag":"kitty-graphics-encode-failed","analyzedSha":"b72f550bc6e75913f48eb49fdd258e1a2df2fe88","analyzedAt":"2026-09-01T04:38:08.254Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}