yorukot/superfile · error

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

Error message

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

What it means

ImagePreview validates its arguments before doing any work and requires both maxWidth and maxHeight to be strictly positive, since they drive resizing and cache keys. This error is returned immediately when either dimension is zero or negative. It is an argument-validation error, not an image-processing failure.

Source

Thrown at src/pkg/file_preview/image_preview.go:72

		cache:       cache.New[string](maxEntries, expiration),
		terminalCap: NewTerminalCapabilities(),
	}

	// Initialize terminal capabilities
	previewer.terminalCap.InitTerminalCapabilities()

	return previewer
}

// ImagePreview generates a preview of an image file.
// Returns (render, rawTransmit, error) where rawTransmit is non-empty only
// for Kitty protocol and should be sent via tea.Raw() to transmit image data
// directly to the terminal, bypassing the cell-based renderer.
func (p *ImagePreviewer) ImagePreview(path string, maxWidth int, maxHeight int,
	defaultBGColor string, sideAreaWidth int) (string, string, error) {
	// Validate dimensions
	if maxWidth <= 0 || maxHeight <= 0 {
		return "", "", fmt.Errorf("dimensions must be positive (maxWidth=%d, maxHeight=%d)", maxWidth, maxHeight)
	}

	// Create dimensions string for cache key
	dimensions := fmt.Sprintf("%d,%d,%s,%d", maxWidth, maxHeight, defaultBGColor, sideAreaWidth)

	// Try Kitty first as it's more modern
	if p.IsKittyCapable() {
		cacheKey := getPreviewObjKey(path, dimensions, RendererKitty)
		rawKey := cacheKey + ":raw"

		if preview, exists := p.cache.Get(cacheKey); exists {
			if rawTransmit, rawExists := p.cache.Get(rawKey); rawExists && rawTransmit != "" {
				return preview, rawTransmit, nil
			}
			// rawKey evicted or empty — treat as cache miss
		}

		render, rawTransmit, err := p.ImagePreviewWithRenderer(

View on GitHub (pinned to b72f550bc6)

Solutions

1. Guard terminal dimensions before calling: skip preview or use defaults when width/height <= 0
2. Wait for the terminal size message (e.g., tea.WindowSizeMsg) before rendering previews
3. Clamp computed dimensions to a minimum of 1
4. Check layout math that subtracts side panels — it may go negative on tiny terminals

Example fix

// before
out, raw, err := previewer.ImagePreview(path, w, h, bg, side)
// after
if w <= 0 || h <= 0 {
	w, h = 40, 20 // fallback dimensions
}
out, raw, err := previewer.ImagePreview(path, w, h, bg, side)

if maxWidth <= 0 || maxHeight <= 0 { skip preview or substitute defaults }

out, raw, err := previewer.ImagePreview(path, w, h, bg, side)
if err != nil && strings.Contains(err.Error(), "dimensions must be positive") {
	return "", "", nil // skip preview gracefully
}

When it happens

Trigger: Calling ImagePreview with maxWidth <= 0 or maxHeight <= 0 — e.g., passing terminal dimensions computed as 0 when the terminal size is unknown, or negative values from unsigned/overflow arithmetic.

Common situations: Terminal size not yet measured (0x0) at first render before a WindowSizeMsg arrives; layout math yielding 0 remaining area after fixed panels consume the full width.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

• invalid renderer : %v
• 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/a1174e104c5d5d99. Report an issue: GitHub.