siyuan-note/siyuan · warning

ErrImageTooLarge

ErrImageTooLarge

Error message

HEIF image exceeds the dimension limit

What it means

ErrImageTooLarge indicates the HEIF image's pixel dimensions (width/height) exceed the package limits — either maxDimension per side or platformMaxPixels total pixels. It is raised after decoding dimensions (DecodeConfigBytes) or after full decode when validating img.Bounds(), in convert, ImageSize, decodeImage, and writeHEIFPreview. This protects against decoding hostile or pathological images that would allocate enormous bitmaps.

Solutions

1. Check dimensions first with goheic.DecodeConfigBytes (or ImageSize) and reject images over the limit with a clear user message
2. Downscale the image with an external tool before importing so it fits within maxDimension/maxPixels
3. If the limit is too strict for your use case, the platform budget (platformMaxPixels) is derived at init — document it rather than bypassing validDimensions

Example fix

// before
result, err := heif.GetOrCreate(ctx, data, opts)
// after
w, h, sizeErr := heif.ImageSize(data)
if errors.Is(sizeErr, heif.ErrImageTooLarge) {
	return fmt.Errorf("image dimensions %dx%d exceed the HEIF conversion limit", w, h)
}
result, err := heif.GetOrCreate(ctx, data, opts)

w, h, err := heif.ImageSize(data)
if errors.Is(err, heif.ErrImageTooLarge) {
	return fmt.Errorf("image exceeds dimension limit")
}

if err != nil {
	if errors.Is(err, heif.ErrImageTooLarge) {
		// reject panorama/huge images with a user-facing message
	}
	return err
}

When it happens

Trigger: convert or ImageSize is called with a HEIF whose decoded width or height exceeds maxDimension, or whose width*height exceeds maxPixels; writeHEIFPreview validates the same bound before encoding output.

Common situations: Panoramic photos (e.g. 10000x4000 iPhone pano HEIC), stitched microscopy/scan images, or maliciously crafted HEIF headers declaring huge dimensions.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• ErrInputTooLarge
• avif: exif data too short
• decode HEIF image
• decode HEIF image
• empty HEIF image

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/0d663e9092dab85f. Report an issue: GitHub.

Appendix: source

Thrown at kernel/heif/convert.go:53

	thumbnailWidth   = 520
	previewQuality   = 90
	thumbnailQuality = 85
	MaxInputBytes    = 32 * 1024 * 1024
	maxDimension     = 65535
	desktopMaxPixels = 50_000_000
	mobileMaxPixels  = 12_500_000
	// 解码层仅接受至多 10-bit 4:2:0、无透明通道的单 slice 图像；这里按解码面、CTU 表、
	// NRGBA 和一次合并变换预留每像素 16 字节，再单独预留源文件、RBSP 副本与 JPEG 输出。
	workingBytesPerPixel = 16
	desktopWorkingBudget = 960 * 1024 * 1024
	mobileWorkingBudget  = 320 * 1024 * 1024
	desktopOutputReserve = 96 * 1024 * 1024
	mobileOutputReserve  = 32 * 1024 * 1024
)

var (
	ErrInputTooLarge = errors.New("HEIF image exceeds the input size limit")
	ErrImageTooLarge = errors.New("HEIF image exceeds the dimension limit")
	ErrInvalidMode   = errors.New("invalid HEIF conversion mode")

	conversionSlots = make(chan struct{}, 1)
	maxPixels       = platformMaxPixels()
)

func platformMaxPixels() int {
	if runtime.GOOS == "android" || runtime.GOOS == "ios" {
		return pixelsWithinBudget(mobileWorkingBudget, mobileOutputReserve, mobileMaxPixels)
	}
	return pixelsWithinBudget(desktopWorkingBudget, desktopOutputReserve, desktopMaxPixels)
}

func ReadFileLimited(path string, maxBytes int64) ([]byte, error) {
	if maxBytes <= 0 {
		return nil, ErrInputTooLarge
	}
	file, err := os.Open(path)

View on GitHub (pinned to 9f775e8a12)