siyuan-note/siyuan · error

ErrUnsupported

ErrUnsupported

Error message

heic: unsupported image

What it means

ErrUnsupported is the package's sentinel error (errors.Is-comparable) for files that are well-formed HEIF but use features this decoder does not implement — most notably grid images whose row*col tile count exceeds maxGridTiles, or whose item data layout exceeds the supported 12-byte structure. The doc comment explicitly tells callers with a fallback decoder to test for this error rather than ErrInvalid.

Source

Thrown at kernel/heif/internal/h265heic/heic.go:44

[DecodeExif] reads the Exif item a file describes its image with, and
[RawExif] and [RawXMP] return the payloads unparsed.
*/
package heic

import (
	"errors"
	"image"
	"io"
	"runtime"

	"github.com/gen2brain/h265/hevc"
)

// ErrUnsupported is returned for a file this package cannot render but which
// is otherwise well formed: an essential property it does not implement, or a
// sample format it has no conversion for. A caller that has another decoder to
// fall back on should test for this one rather than [ErrInvalid].
var ErrUnsupported = errors.New("heic: unsupported image")

// DefaultFrameSizeLimit 限制文件头能够请求分配的像素面积。
const DefaultFrameSizeLimit = 50_000_000

// ColorInfo describes the color space an image was decoded from.
type ColorInfo struct {
	Primaries uint16
	Transfer  uint16
	Matrix    uint16
	FullRange bool
	// ICCP is the embedded ICC profile, for files that carry one in place of
	// an nclx description. It aliases the input, so it is not a copy.
	ICCP []byte
}

// Options controls decoding.
type Options struct {
	// AutoRotate applies the clap/irot/imir transforms, forcing NRGBA output

View on GitHub (pinned to 8641553a1f)

Solutions

  1. Use errors.Is(err, h265heic.ErrUnsupported) to detect it and fall back to another decoder (system HEIF framework, ImageMagick, external converter)
  2. Pre-convert oversized grid HEIFs to JPEG/PNG before importing
  3. Check whether raising the decoder's limits (maxGridTiles/FrameSizeLimit options) accommodates your images
  4. Verify the file opens in Preview/another viewer to confirm it is a capability gap, not corruption (corruption yields ErrInvalid instead)

Example fix

// before
img, err := h265heic.DecodeBytes(data, opts)
if err != nil {
	return nil, err
}
// after
img, err := h265heic.DecodeBytes(data, opts)
if errors.Is(err, h265heic.ErrUnsupported) {
	return fallbackDecode(data) // system decoder / external tool
}
if err != nil {
	return nil, err
}
Defensive patterns

Strategy: fallback

Validate before calling

if errors.Is(err, h265heic.ErrUnsupported) {
	log.Infof("HEIF uses unsupported features; using fallback decoder")
}
// pre-check for very large grids when you control the pipeline:
// reject images whose dimensions imply tile counts beyond maxGridTiles

Try / catch

img, err := h265heic.DecodeBytes(data, opts)
if errors.Is(err, h265heic.ErrUnsupported) {
	return systemDecoder(data) // macOS/Windows HEIF codec, or external CLI
}
if err != nil {
	return err // genuine corruption (ErrInvalid) or other failure
}

Prevention

When it happens

Trigger: decodeImage/decodeTiles/consumeDecodedBytes/parseGrid/gridOf on: (1) a grid-derived image with rows*cols > maxGridTiles (very large multi-tile photos), (2) grid item data with dataSize > 12 bytes (unsupported gridInfo layout), (3) sample formats or essential properties the decoder has no conversion for.

Common situations: ProRAW/ProMAX iPhone photos stored as large grid HEIFs with many tiles; images produced by newer camera firmware using grid extensions; HDR/auxiliary-layer images needing unimplemented conversions.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/78bf9b3b7d4ef07a. Report an issue: GitHub.