yorukot/superfile · error

dimensions must be positive (maxWidth=%d, maxHeight=%d)

Error message

dimensions must be positive (maxWidth=%d, maxHeight=%d)

What it means

This error is thrown by the Kitty graphics-protocol image renderer when the caller supplies a non-positive maxWidth or maxHeight. The renderer needs a positive cell budget to compute the scaled destination grid (dstCols/dstRows), so it fails fast before querying terminal cell size. It is a caller-contract violation, not an environment failure.

Source

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

// KittyImageResult holds both the placeholder string for the cell buffer
// and the raw transmission data to send directly to the terminal.
type KittyImageResult struct {
	// Placeholders is the Unicode placeholder string for embedding in the view.
	// It contains kitty.Placeholder characters with diacritics.
	Placeholders string
	// RawTransmit is the Kitty graphics APC data to send via tea.Raw().
	// It transmits the image data to the terminal out-of-band.
	RawTransmit string
}

// renderWithKittyUsingTermCap renders an image using Kitty graphics protocol
// with Unicode virtual placeholders (compatible with cell-based renderers).
func (p *ImagePreviewer) renderWithKittyUsingTermCap(img image.Image, path string,
	originalWidth, originalHeight, maxWidth, maxHeight int, _ int,
) (*KittyImageResult, error) {
	if maxWidth <= 0 || maxHeight <= 0 {
		return nil, fmt.Errorf("dimensions must be positive (maxWidth=%d, maxHeight=%d)", maxWidth, maxHeight)
	}

	cellSize := p.terminalCap.GetTerminalCellSize()
	pixelsPerColumn := cellSize.PixelsPerColumn
	pixelsPerRow := cellSize.PixelsPerRow

	slog.Debug("pixelsPerColumn", "pixelsPerColumn", pixelsPerColumn, "pixelsPerRow", pixelsPerRow)

	imgRatio := float64(originalWidth) / float64(originalHeight)
	termRatio := float64(maxWidth*pixelsPerColumn) / float64(maxHeight*pixelsPerRow)

	var dstCols, dstRows int
	if imgRatio > termRatio {
		dstCols = maxWidth
		dstRows = int(float64(dstCols*pixelsPerColumn) / imgRatio / float64(pixelsPerRow))
	} else {
		dstRows = maxHeight
		dstCols = int(float64(dstRows*pixelsPerRow) * imgRatio / float64(pixelsPerColumn))

View on GitHub (pinned to b72f550bc6)

Solutions

1. Ensure the preview is only rendered after a real terminal size is known (guard on the WindowSizeEvent / initial layout).
2. Clamp dimensions to a minimum, e.g. if maxWidth < 1 { maxWidth = 1 }; if maxHeight < 1 { maxHeight = 1 } before calling the renderer.
3. Skip image rendering when the pane is too small and fall back to the text/file-info preview.
4. Add a unit test asserting renderWithKittyUsingTermCap is never invoked with non-positive dims.

Example fix

// before
res, err := previewer.ImagePreviewWithRenderer(img, path, w, h, 0, 0)
// after
if w <= 0 || h <= 0 { return nil } // pane not laid out yet
res, err := previewer.ImagePreviewWithRenderer(img, path, w, h, max(w, 1), max(h, 1))

func canRender(w, h int) bool { return w > 0 && h > 0 }
if !canRender(previewW, previewH) { return nil } // skip render until layout known

if res, err := previewer.ImagePreviewWithRenderer(img, path, w, h); err != nil {
    if strings.Contains(err.Error(), "dimensions must be positive") {
        return nil // pane not laid out; retry on next size event
    }
    return err
}

When it happens

Trigger: Calling ImagePreviewWithRenderer (which calls renderWithKittyUsingTermCap) with maxWidth<=0 or maxHeight<=0 — e.g. a preview pane that was never laid out, a width/height computed from a zero-size terminal, or an off-by-one subtraction like width-1 on a 1-column pane producing 0.

Common situations: TUI apps rendering previews before the first WindowSizeEvent arrives; panes collapsed to zero width; tests constructing an ImagePreviewer without setting dimensions; integer truncation from dividing terminal size by a splitter factor yielding 0.

Related errors

• failed to encode kitty graphics: %w
• source path does not exist: %s
• failure while extracting content : %w
• failure in extracted content : %w
• invalid row range [%v, %v], line count : %v

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