siyuan-note/siyuan · error

ErrImageTooLarge

ErrImageTooLarge

Error message

HEIF image exceeds the dimension limit

What it means

ErrImageTooLarge (kernel/heif/convert.go:53) fires when pixel dimensions exceed the platform budget: at most 50,000,000 px on desktop and 12,500,000 px on mobile (both further squeezed by a 16 bytes-per-pixel working-memory budget), with a per-side cap of 65535 px (maxDimension). It is checked from the HEIF header via goheic.DecodeConfigBytes before full decode (convert.go:188) and again on decoded bounds (127/171), so oversized images fail fast without huge allocations.

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 afa823b6b4)

Solutions

1. Downscale below the platform cap (desktop 50 MP / mobile 12.5 MP, each side <= 65535 px)
2. Convert the panorama to JPEG, which bypasses the HEIF decode budget
3. Tile very large images into multiple assets

Example fix

# before: insert panorama_120mp.heic
# -> HEIF image exceeds the dimension limit

# after: downscale under the 50 MP desktop budget, then insert
magick panorama_120mp.heic -resize 50% panorama_small.heic

// Go: probe before committing the asset; ImageSize reports the same sentinel
_, _, err := heif.ImageSize(data)
if errors.Is(err, heif.ErrImageTooLarge) {
    // downscale or convert to JPEG, then retry the insert
}

func isHEIFImageTooLarge(err error) bool {
    return errors.Is(err, heif.ErrImageTooLarge)
}

On ErrImageTooLarge from preview/size APIs, re-encode the asset with an external tool (downscale under 50 MP desktop / 12.5 MP mobile, sides <= 65535 px) or convert it to JPEG, then retry once - do not loop on the same bytes.

When it happens

Trigger: Inserting a >50 MP HEIF panorama or medium-format export on desktop; the same image on Android/iOS where the cap is 12.5 MP; any side exceeding 65535 px, caught at header or post-decode check.

Common situations: Stitched panoramas; 100 MP 'super-res' phone modes; desktop-size images synced to and opened on the mobile app where the budget is smaller.

Related errors

• ErrInputTooLarge
• empty HEIF image
• source is not an encrypted asset
• invalid asset type [%s]
• --file is required

AI-assisted analysis of siyuan-note/siyuan@afa823b6b4 (2026-08-18). Data as JSON: /api/errors/0d663e9092dab85f. Report an issue: GitHub.