siyuan-note/siyuan · error

read HEIF image dimensions

Error message

read HEIF image dimensions: %w

What it means

decodeImage wraps a failure from goheic.DecodeConfigBytes (reading just the image header/dimensions) as "read HEIF image dimensions: %w". The original goheic error is wrapped with %w so errors.Is/As retain the cause. This fires before full decode, meaning the HEIF container itself could not be parsed even for metadata.

Solutions

1. Verify the file is a genuine HEIF container (magic bytes ftypheic/heix/msf1) before conversion
2. Re-obtain the asset from its source; the container is unreadable, so content is likely lost
3. If the file is actually a JPEG/PNG, route it to the correct image path instead of the HEIF pipeline

Example fix

// before
w, h, err := heif.ImageSize(data)
if err != nil { return err }
// after
w, h, err := heif.ImageSize(data)
if err != nil {
	var wrapped error
	if errors.As(err, &wrapped) && strings.Contains(err.Error(), "read HEIF image dimensions") {
		return fmt.Errorf("asset is not a valid HEIF container: %v", err)
	}
	return err
}

// check HEIF brand bytes before calling
if len(data) < 12 || !bytes.Equal(data[4:8], []byte("ftyp")) {
	return fmt.Errorf("not a HEIF container")
}

if _, err := heif.ImageSize(data); err != nil {
	if strings.Contains(err.Error(), "read HEIF image dimensions:") {
		// container unreadable; %w-wrapped goheic cause available via errors.Unwrap
	}
	return err
}

When it happens

Trigger: convert or ImageSize is called on bytes that are not a parseable HEIF/HEIC container — wrong format (JPEG/PNG mislabeled .heic), truncated header, or damaged ISOBMFF boxes.

Common situations: Files renamed to .heic without conversion, partial downloads/failed transfers, asset corruption on disk or after a bad sync.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

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

Appendix: source

Thrown at kernel/heif/convert.go:186

	}
	width, height = img.Bounds().Dx(), img.Bounds().Dy()
	if !validDimensions(width, height) {
		return 0, 0, ErrImageTooLarge
	}
	return width, height, nil
}

func decodeImage(source []byte) (img image.Image, err error) {
	defer func() {
		if recovered := recover(); recovered != nil {
			img = nil
			err = fmt.Errorf("decode HEIF image: %v", recovered)
		}
	}()

	config, err := goheic.DecodeConfigBytes(source)
	if err != nil {
		return nil, fmt.Errorf("read HEIF image dimensions: %w", err)
	}
	if !validDimensions(config.Width, config.Height) {
		return nil, ErrImageTooLarge
	}

	img, err = goheic.DecodeBytes(source, goheic.Options{
		AutoRotate:     true,
		FrameSizeLimit: maxPixels,
		Threads:        1,
	})
	if err != nil {
		return nil, fmt.Errorf("decode HEIF image: %w", err)
	}
	return img, nil
}

func validDimensions(width, height int) bool {
	return width > 0 && height > 0 && width <= maxDimension && height <= maxDimension &&

View on GitHub (pinned to 9f775e8a12)